diff --git a/10-systems/servers/smart-home-server.md b/10-systems/servers/smart-home-server.md index e2cab5f..2904c08 100644 --- a/10-systems/servers/smart-home-server.md +++ b/10-systems/servers/smart-home-server.md @@ -47,3 +47,14 @@ **Response Format:** Returns a JSON object with `status: true` and the `return` value from the PHP script. + +## GAuth OAuth State/PKCE Storage (file-based, applied 2026-09-04) + +The Google OAuth flow no longer keeps OAuth `state` and PKCE verifiers in the PHP session. The callback arrives from Chrome Custom Tab, which does not share the `PHPSESSID` cookie with the app WebView session, so session-backed stores lost the state between the authorize redirect and the callback. + +- **New store classes:** `SHServ/Integrations/GAuth/Store/FileStateStore.php` and `SHServ/Integrations/GAuth/Store/FilePkceStore.php` (implement `GNexus\GAuth\Contract\StateStoreInterface` / `PkceStoreInterface`). Records are JSON files keyed by `sha256(state)` with an `expires_at` field; expired records are deleted on read. +- **Wiring:** `AuthService.php` now instantiates `FileStateStore` / `FilePkceStore` (previously `SessionStateStore` / `SessionPkceStore`). `AuthController.php` reads the `returnTo` context via `FileStateStore->getContext($state)` before `handleCallback()` forgets the state. +- **Storage directories:** `/home/shome/smart-home-server/server/Cache/gauth/state` and `.../Cache/gauth/pkce`, owner `www-data:shome`, mode `770` (PHP-FPM runs as `www-data`). +- **Old session store classes** (`SessionStateStore.php`, `SessionPkceStore.php`) remain in `Store/` but are unused. +- **Rollback backups:** `AuthService.php.bak-20260904` and `Controllers/AuthController.php.bak-20260904` next to the originals. +- No php-fpm/nginx restart was required (`opcache.validate_timestamps=1`); all touched files passed `php -l`. diff --git a/90-maintenance/pending-changes/20260904105837-12fb622e.json b/90-maintenance/pending-changes/20260904105837-12fb622e.json new file mode 100644 index 0000000..ff6511d --- /dev/null +++ b/90-maintenance/pending-changes/20260904105837-12fb622e.json @@ -0,0 +1,19 @@ +{ + "id": "20260904105837-12fb622e", + "kind": "doc", + "target": "10-systems/servers/smart-home-server.md", + "summary": "Document file-based GAuth OAuth state/PKCE stores applied on 2026-09-04", + "reason": "Applied the file-based OAuth state/PKCE store fix on shome (2026-09-04); storage locations, wiring, and rollback backups are durable operational facts for future auth debugging.", + "payload": { + "content": "---\nowner: gmikcon\nstatus: active\nlast_reviewed: 2026-09-04\nreview_interval: 90d\nconfidence: medium\nsource_of_truth: owner-confirmed-and-ssh-host\n---\n\n# Smart Home Server\n\n... (existing content) ...\n\n## Access & Time (verified 2026-09-04)\n\n- **SSH:** `shome@192.168.1.101`, port 22, password authentication (password stored in gnexus-creds secret `smart-home-server-creds`). User `shome` has sudo rights (password required, use `sudo -S`).\n- **Timezone:** `Europe/Kyiv` (EEST, UTC+3). Fixed on 2026-09-04 — previously `Etc/UTC`, which made server local time lag 3 hours behind real Kyiv time. NTP service active, system clock synchronized: yes.\n- **Quick time check without SSH:** the nginx `Date` response header on `http://192.168.1.101/` reflects server system time (UTC).\n\n## API Usage: Triggering Actions\n\nThe smart-home platform allows triggering `ControlScripts` actions via HTTP POST. This is the preferred way for external automation or manual control without the web client.\n\n### Endpoint: `POST /api/v1/scripts/actions/run`\n\n**Request Body (JSON):**\n```json\n{\n \"alias\": \"action_alias_here\",\n \"params\": {}\n}\n```\n\n**Example: Toggle Bedroom Light**\n```bash\ncurl -X POST http://192.168.1.101/api/v1/scripts/actions/run \\\n -H \"Content-Type: application/json\" \\\n -d '{\"alias\": \"master_room_lamp_switcher\", \"params\": {}}'\n```\n\n**Example: Toggle Hallway Light (2nd Floor)**\n```bash\ncurl -X POST http://192.168.1.101/api/v1/scripts/actions/run \\\n -H \"Content-Type: application/json\" \\\n -d '{\"alias\": \"hallway2_lamp_switcher\", \"params\": {}}'\n```\n\n**Response Format:**\nReturns a JSON object with `status: true` and the `return` value from the PHP script.\n\n## GAuth OAuth State/PKCE Storage (file-based, applied 2026-09-04)\n\nThe Google OAuth flow no longer keeps OAuth `state` and PKCE verifiers in the PHP session. The callback arrives from Chrome Custom Tab, which does not share the `PHPSESSID` cookie with the app WebView session, so session-backed stores lost the state between the authorize redirect and the callback.\n\n- **New store classes:** `SHServ/Integrations/GAuth/Store/FileStateStore.php` and `SHServ/Integrations/GAuth/Store/FilePkceStore.php` (implement `GNexus\\GAuth\\Contract\\StateStoreInterface` / `PkceStoreInterface`). Records are JSON files keyed by `sha256(state)` with an `expires_at` field; expired records are deleted on read.\n- **Wiring:** `AuthService.php` now instantiates `FileStateStore` / `FilePkceStore` (previously `SessionStateStore` / `SessionPkceStore`). `AuthController.php` reads the `returnTo` context via `FileStateStore->getContext($state)` before `handleCallback()` forgets the state.\n- **Storage directories:** `/home/shome/smart-home-server/server/Cache/gauth/state` and `.../Cache/gauth/pkce`, owner `www-data:shome`, mode `770` (PHP-FPM runs as `www-data`).\n- **Old session store classes** (`SessionStateStore.php`, `SessionPkceStore.php`) remain in `Store/` but are unused.\n- **Rollback backups:** `AuthService.php.bak-20260904` and `Controllers/AuthController.php.bak-20260904` next to the originals.\n- No php-fpm/nginx restart was required (`opcache.validate_timestamps=1`); all touched files passed `php -l`." + }, + "status": "applied", + "created_at": "2026-09-04T10:58:37Z", + "updated_at": "2026-09-04T10:58:38Z", + "applied_at": "2026-09-04T10:58:38Z", + "validation": { + "status": "ok", + "issue_count": 0, + "issues": [] + } +}