---
owner: gmikcon
status: active
last_reviewed: 2026-09-04
review_interval: 90d
confidence: medium
source_of_truth: owner-confirmed-and-ssh-host
---

# Smart Home Server

... (existing content) ...

## Access & Time (verified 2026-09-04)

- **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`).
- **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.
- **Quick time check without SSH:** the nginx `Date` response header on `http://192.168.1.101/` reflects server system time (UTC).

## API Usage: Triggering Actions

The 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.

**Important:** only aliases registered by live code in `automation/Scopes/` work. Legacy aliases (`master_room_lamp_switcher`, `hallway2_lamp_switcher`, etc.) still have `enabled` rows in the `scripts` DB table but are NOT registered by code and return null. See `10-systems/automations/smart-home-overview.md` for the verified live action list.

### Endpoint: `POST /api/v1/scripts/actions/run`

**Request Body (JSON):**
```json
{
  "alias": "action_alias_here",
  "params": {}
}
```

**Example: Toggle Bedroom Light**
```bash
curl -X POST http://192.168.1.101/api/v1/scripts/actions/run \
     -H "Content-Type: application/json" \
     -d '{"alias": "master_toggle", "params": {}}'
```

**Example: Toggle Hallway Light (2nd Floor)**
```bash
curl -X POST http://192.168.1.101/api/v1/scripts/actions/run \
     -H "Content-Type: application/json" \
     -d '{"alias": "hall2_toggle", "params": {}}'
```

**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`.
- **Verification (2026-09-04):** the broken flow was emulated server-side — login from one cookie jar, callback from a clean jar without the shared `PHPSESSID`. State validation now passes cross-context; with a fake code the failure moves to the token-exchange step (`Authorization code is invalid or expired` in `php:Auth` logs), confirming the fix.
