# SecureCam share relay

A small PHP application for your own webspace. It lets people you share a
camera with watch it through **your** webspace, so your home network needs **no
open port**. SecureCam at home connects out to the relay, never the other way
round.

Design, protocol and security model: `docs/strategies/SHARE-RELAY.md` in the
SecureCam repository.

## Requirements

- PHP 8.0 or newer
- HTTPS for the relay address
- A writable directory for `data/` (ideally outside the web root)
- No database, no cron and no long-running processes are needed

## Install

1. In SecureCam: **Verwaltung → Freigaben → Freigabe-Relay**. Enter the future
   address, enable the relay, save, then **download the relay package**. The zip
   contains a generated `config.php` with your publisher key.
2. Upload the `securecam-relay/` folder to your webspace.
3. Point a (sub)domain's document root at `securecam-relay/public/`.

   If your host cannot do that and serves the whole folder, the `.htaccess`
   files still deny `app/`, `data/` and `config.php`. The connection test warns
   in that case.
4. Enter the public URL of `public/` as the relay address in SecureCam, for
   example `https://cams.example.org`, and press **Verbindung testen**.

Links created with **Über Relay** now look like `https://cams.example.org/s#…`.

## Layout

```
securecam-relay/
  config.php        generated: publisher key (keep private)
  app/              relay code (not web-reachable)
  data/             created on first use: grant mirrors, short video window
  public/           web root: index.php, .htaccess, assets/
```

## Behaviour and privacy

- **Tokens:** the share token is in the part after `#`, which browsers never
  send to a server. It reaches the relay only as a request header, so it does
  not appear in access logs.
- **Grant mirror:** the relay stores only what it needs to refuse bad requests:
  a hash of the token, the camera ids and names, and the expiry. It never sees
  labels, creators or accounts.
- **Video:** it is uploaded only while someone watches, as a sliding window of
  about 12 seconds. Sessions nobody uploads to for 90 seconds are deleted.
  **In this version segments are not end-to-end encrypted**; they are protected
  by HTTPS in transit only.
- **Revocation:** SecureCam tells the relay immediately. Independently of that,
  home stops uploading for a revoked link, and the relay enforces expiry on its
  own.
- **Cleanup** runs automatically during normal requests. With cron you can also
  run `php public/index.php gc`.

## Local testing

```
php -S 127.0.0.1:8080 -t public public/index.php
```

Local testing needs a `config.php` with `'allow_plaintext' => true`. **Never**
set that on a public host.