Add admin dashboard and Pocket ID auth notes

docs/ADMIN.md

@@ -0,0 +1,49 @@
+# FamilyFed.ie admin notes
+
+The admin dashboard is generated at `/admin/index.html`. To make
+`https://admin.familyfed.ie/` show the dashboard, configure the web server or
+reverse proxy for that hostname to serve `dist/admin/index.html` as its root
+document.
+
+Protect `admin.familyfed.ie` at the web server, reverse proxy, or hosting layer
+with Pocket ID authentication. Require the Pocket ID user group
+`familyfed_admin`. The generated page has `noindex`, but a static page cannot
+enforce a secure admin login by itself.
+
+See `docs/POCKET-ID-AUTH.md` for the exact proxy/auth requirements.
+
+## Content changes
+
+- Calendar events live in `src/data/events.ts`.
+- Speeches live in `content/speeches/<year>/<slug>.md`.
+- The admin page includes builders that generate valid snippets/files for both.
+
+Because this is a static Astro site, the browser cannot securely write content
+back into the repository by itself. Commit generated content changes to the
+repository and deploy as usual.
+
+## Contact form
+
+Set `PUBLIC_CONTACT_FORM_ENDPOINT` during the build to make the contact form
+send real submissions through a hosted form provider such as Formspree, Basin,
+Getform, or a self-hosted endpoint.
+
+Optional variables:
+
+- `PUBLIC_CONTACT_RECIPIENTS`: comma-separated mail fallback recipients.
+- `PUBLIC_CONTACT_SUBMISSIONS_URL`: admin dashboard URL for form submissions.
+
+If no endpoint is configured, the form falls back to opening the visitor's email
+application with the message filled in.
+
+For deployment, add the matching variables as Forgejo secrets. The deploy
+workflow passes them into the Astro build.
+
+## Analytics
+
+Set `PUBLIC_PLAUSIBLE_DOMAIN=familyfed.ie` to load Plausible analytics on the
+public site. If using a self-hosted Plausible instance, set
+`PUBLIC_PLAUSIBLE_SCRIPT_SRC` to the script URL.
+
+Set `PUBLIC_ANALYTICS_DASHBOARD_URL` to the analytics dashboard URL so the admin
+page can link directly to visitor reports.

docs/POCKET-ID-AUTH.md

@@ -0,0 +1,75 @@
+# Pocket ID auth for admin.familyfed.ie
+
+`admin.familyfed.ie` must be protected before traffic reaches the static Astro
+files. Pocket ID is an OIDC provider, so the auth check belongs in the reverse
+proxy or auth middleware.
+
+Required policy:
+
+- Host: `admin.familyfed.ie`
+- Required Pocket ID group: `familyfed_admin`
+- Static upstream/root: `dist/admin/index.html`
+
+## Recommended Tinyauth setup
+
+Pocket ID's proxy guide points to Tinyauth for reverse-proxy protection, and
+Tinyauth supports Pocket ID groups through the `oauth.groups` app label.
+
+Create a Pocket ID OIDC client:
+
+- Name: `FamilyFed Admin`
+- Callback URL: `https://auth.familyfed.ie/api/oauth/callback/pocketid`
+- Scopes: `openid email profile groups`
+
+Configure Tinyauth with the Pocket ID client:
+
+```yaml
+environment:
+  TINYAUTH_OAUTH_AUTOREDIRECT: pocketid
+  TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTID: "<pocket-id-client-id>"
+  TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTSECRET: "<pocket-id-client-secret>"
+  TINYAUTH_OAUTH_PROVIDERS_POCKETID_AUTHURL: "https://pocket-id.familyfed.ie/authorize"
+  TINYAUTH_OAUTH_PROVIDERS_POCKETID_TOKENURL: "https://pocket-id.familyfed.ie/api/oidc/token"
+  TINYAUTH_OAUTH_PROVIDERS_POCKETID_USERINFOURL: "https://pocket-id.familyfed.ie/api/oidc/userinfo"
+  TINYAUTH_OAUTH_PROVIDERS_POCKETID_REDIRECTURL: "https://auth.familyfed.ie/api/oauth/callback/pocketid"
+  TINYAUTH_OAUTH_PROVIDERS_POCKETID_SCOPES: "openid email profile groups"
+  TINYAUTH_OAUTH_PROVIDERS_POCKETID_NAME: "Pocket ID"
+```
+
+Add app access labels for the admin host:
+
+```yaml
+labels:
+  tinyauth.apps.familyfed-admin.config.domain: "admin.familyfed.ie"
+  tinyauth.apps.familyfed-admin.oauth.groups: "familyfed_admin"
+```
+
+Users outside `familyfed_admin` should receive the unauthorized page from the
+auth middleware and never reach the static admin HTML.
+
+## Caddy with caddy-security
+
+If the live proxy is Caddy with `caddy-security`, create a Pocket ID OIDC client
+with this callback URL:
+
+```text
+https://admin.familyfed.ie/caddy-security/oauth2/generic/authorization-code-callback
+```
+
+Configure the authorization policy to allow only users whose OIDC groups claim
+contains `familyfed_admin`, then serve or reverse-proxy the static admin output.
+Pocket ID's own guide documents the Caddy callback shape and OIDC provider
+settings; the group condition must be added in the Caddy authorization policy.
+
+## Deployment checks
+
+The site build now verifies that `dist/admin/index.html` exists. That confirms
+the static admin page is available for the host, but it does not prove the
+external proxy has enabled Pocket ID. Verify live protection with:
+
+```bash
+curl -I https://admin.familyfed.ie/
+```
+
+Expected unauthenticated behavior is a redirect to the Pocket ID/Tinyauth login
+or a `401`/`403` response from the auth middleware.