Member invites, gallery resync, content and operator docs

- Invite flow: admin issue/revoke on join requests, public single-use claim links (hash-only tokens, 7-day expiry, no state reveal), claim creates the Member account and marks the request accepted - Gallery: admin status page plus resync endpoint; sync refreshes thumbnails whose content changed; tools/gallery contract and checker - Docs: public content page, admin-only operator runbook, api.md invite/gallery sections, all routes in the live API docs, docs reachability gate test - Screenshots cover the new pages; version 1.0.18
2026-10-06 02:56:08 +02:00
parent e512556703
commit 9fb4d65787
36 changed files with 1147 additions and 19 deletions
@@ -0,0 +1,18 @@
+<!-- retoor <retoor@molodetz.nl> -->
+{% extends "admin/base_admin.html" %}
+{% block admin_content %}
+<h1>Gallery</h1>
+<div class="stat-cards">
+  <div class="stat-card"><span class="value">{{ flyers }}</span><span class="name">Flyers</span></div>
+  <div class="stat-card"><span class="value">{{ memes }}</span><span class="name">Memes</span></div>
+</div>
+{% if missing %}
+<div class="notice error" role="alert"><p>Missing source files:</p><ul>{% for filename in missing %}<li><code>{{ filename }}</code></li>{% endfor %}</ul></div>
+{% else %}
+<p class="muted">All catalogued source files are present.</p>
+{% endif %}
+<form method="post" action="/admin/gallery/resync">
+  <div class="actions"><button class="button" type="submit" data-loading>Resync gallery</button></div>
+</form>
+<p class="muted">Resync re-reads the source files, refreshes changed thumbnails and retires removed entries. New works arrive through deploy first.</p>
+{% endblock %}
@@ -7,6 +7,8 @@
  <div class="stat-card"><span class="value">{{ open_joins }}</span><span class="name">Open join requests</span></div>
  <div class="stat-card"><span class="value">{{ user_count }}</span><span class="name">Accounts</span></div>
  <div class="stat-card"><span class="value">{{ deleted_count }}</span><span class="name">In trash</span></div>
+  <div class="stat-card"><span class="value">{{ flyer_count }}</span><span class="name">Flyers</span></div>
+  <div class="stat-card"><span class="value">{{ meme_count }}</span><span class="name">Memes</span></div>
 </div>
-<div class="actions"><a class="button" href="/admin/posts/new">New post</a><a class="button ghost" href="/admin/joins">View join requests</a></div>
+<div class="actions"><a class="button" href="/admin/posts/new">New post</a><a class="button ghost" href="/admin/joins">View join requests</a><a class="button ghost" href="/admin/gallery">Gallery</a></div>
 {% endblock %}
@@ -0,0 +1,9 @@
+<!-- retoor <retoor@molodetz.nl> -->
+{% extends "admin/base_admin.html" %}
+{% block admin_content %}
+<h1>Invite issued</h1>
+<p>Send this link to <strong>{{ join.name }}</strong> ({{ join.contact }}). It is shown once and expires {{ local_dt(expires_at) }}.</p>
+<div class="notice"><p><code>{{ claim_url }}</code></p></div>
+<p class="muted">Issuing a new invite revokes this one. The request flips to accepted when the link is claimed.</p>
+<p><a class="button ghost" href="/admin/joins">Back to join requests</a></p>
+{% endblock %}
@@ -12,7 +12,7 @@
    <td>{{ item.contact }}</td>
    <td>{% if item.repo_url %}<a href="{{ item.repo_url }}" rel="nofollow noopener" target="_blank">{{ item.repo_url }}</a>{% if item.link_status %}<br><span class="muted">{{ item.link_status }}{% if item.link_title %}: {{ item.link_title }}{% endif %}</span>{% endif %}{% else %}<span class="muted">none</span>{% endif %}</td>
    <td>{{ item.message }}</td>
-    <td><span class="status {{ item.status }}">{{ item.status }}</span></td>
+    <td><span class="status {{ item.status }}">{{ item.status }}</span>{% if item.invite_open %}<br><span class="muted">invite until {{ local_dt(item.invite_expires_at) }}</span>{% endif %}</td>
    <td>{{ local_dt(item.created_at) }}</td>
    <td class="actions">
      <form method="post" action="/admin/joins/{{ item.uid }}/status">
@@ -20,6 +20,8 @@
        <button class="button ghost small" type="submit">Set</button>
      </form>
      {% if item.repo_url %}<form method="post" action="/admin/joins/{{ item.uid }}/check"><button class="button ghost small" type="submit" data-loading>Check link</button></form>{% endif %}
+      {% if item.invite_open %}<form method="post" action="/admin/joins/{{ item.uid }}/invite/revoke"><button class="button ghost small" type="submit">Revoke invite</button></form>
+      {% elif item.status != 'declined' %}<form method="post" action="/admin/joins/{{ item.uid }}/invite"><button class="button ghost small" type="submit" data-loading>Issue invite</button></form>{% endif %}
    </td>
  </tr>
  {% else %}
@@ -23,6 +23,14 @@ curl -H 'Accept: application/json' https://molodetz.nl/roll

 Errors have the shape `{"error": {"status": 404, "message": "..."}}`. Validation errors return `422` with `{"error": "validation", "fields": [...], "messages": [...]}`.

+## Invites
+
+Membership starts from a join request plus an admin-issued invite. Admins call `POST /admin/joins/{uid}/invite` (returns `claim_url` and `expires_at` in `data`) and `POST /admin/joins/{uid}/invite/revoke`. The public claim is `GET` and `POST /invite/{token}` with `username`, `email`, `password`, `password_confirm` and `terms`. Claim links are single use and every dead link answers 404 with the same message.
+
+## Gallery
+
+`GET /admin/gallery` reports live flyer and meme counts plus catalogued source files missing from disk. `POST /admin/gallery/resync` re-reads the sources and retires removed entries. See [Galleries and content](/docs/content) for how publishing works.
+
 ## Old paths

 The Dutch paths from before (`/rol`, `/standaard`, `/mensen`, `/binnen`, `/voorwaarden`) answer with a 301 to their English replacement. Query strings are kept.
@@ -0,0 +1,26 @@
+# Galleries and content
+
+The flyers and the memes are curated galleries. Every work is a source file plus a catalogue entry with its caption. Nothing is uploaded through the site: new works arrive with a deploy, and the database reconciles at boot.
+
+## Flyers
+
+Flyers live at [/flyers](/flyers). New flyers are 1080 by 1350 (portrait). The first flyer in the catalogue is the featured one on the home page.
+
+## Memes
+
+Memes live at [/memes](/memes). New memes are 1080 by 1080 (square). Some older memes are 1280 by 720 (landscape) from the previous generation; they stay as they are.
+
+## How publishing works
+
+1. The source file lands in the media directory and the catalogue entry (filename, kind, caption) lands in the code, both through deploy.
+2. At boot the sync reads every catalogued source file and upserts the database row: position, dimensions, perceptual hash and a generated webp thumbnail.
+3. Near-duplicates are skipped: a work whose image hash is within a small distance of an already synced work is logged and left out, so an accidental double never shows twice.
+4. Removed works are retired, never hard-deleted: their rows are soft-deleted and disappear from the galleries.
+
+An administrator can also press *Resync* under *Admin, Gallery* after a deploy. Resync re-reads the sources, refreshes thumbnails whose content changed, reports missing source files and retires removed entries. It never invents catalogue entries.
+
+## Freshness
+
+Public pages are cached for seconds to minutes (landing, settings, sitemap each have their own short TTL), so a fresh deploy can take a moment to show everywhere. The exact TTLs are operator detail; see the operator runbook under *Admin*.
+
+Old Dutch paths (`/rol`, `/mensen`, and friends) redirect with 301 to their English replacements; see [API and authentication](/docs/api).
@@ -0,0 +1,54 @@
+# Operator runbook
+
+This page is only visible to administrators. It covers the flows that move people and content through the system: invites, gallery updates, trash, caches and the environment rules.
+
+## Member invites
+
+Join requests end in membership through an invite link. The full flow:
+
+1. Read the request under *Admin, Join requests*. `Check link` fetches the linked work once and stores the outcome on the request.
+2. Move the status to `contacted` while talking, `declined` to refuse. A declined request cannot receive an invite.
+3. Press *Issue invite*. The claim link is shown once on the confirmation page: copy it and send it to the person yourself. There is no email sending.
+4. The person opens the link, picks a name and password and accepts the house rules. Claiming creates a Member account, logs them in and flips the request to `accepted`.
+
+Rules the code enforces:
+
+- One open invite per request. Issuing a new one revokes the previous.
+- Single use, 7 day expiry by default (`invite_expiry_days` setting).
+- Only a hash of the token is stored; a database read never yields a usable link.
+- Unknown, used, revoked and expired links all answer identically (404, same message), so links cannot be probed for state.
+- If the contact looked like an email address, the claim must use that same address. Handle-style contacts leave the email free for the claimer to fill in.
+- `Revoke invite` kills the open link without touching the request.
+
+API: `POST /admin/joins/{uid}/invite` returns `{"claim_url", "expires_at"}` in `data` (JSON only; the HTML form renders the one-time page instead). `POST /admin/joins/{uid}/invite/revoke` returns `{"revoked": n}`. Public claim is `GET` and `POST /invite/{token}`.
+
+## Gallery updates
+
+Source files plus catalogue entries arrive through deploy. After deploy, press *Resync* under *Admin, Gallery* (or `POST /admin/gallery/resync`). The status page shows live flyer and meme counts and lists catalogued files missing from disk. Resync refreshes thumbnails whose content changed and retires removed entries. Boot runs the same sync, so a production rebuild never needs the button.
+
+## Trash
+
+Soft-deleted rows carry a `deleted_at` stamp (UTC ISO). Restore and purge match the exact stamp across every soft-delete table, so one trash event restores or purges as a unit. Purge is permanent; there is no undo.
+
+## Sessions and suspension
+
+Login resolution order is session cookie, `X-API-KEY`, Bearer, Basic; see [API and authentication](/docs/api). Sessions live 7 days, 30 with *remember me* (`session_max_age_days`, `session_remember_days`). A suspended account (`suspended_until` in the future) is refused on every mutating route outside `/auth` with 403. Users whose `terms_version` lags behind the setting are sent to `/terms` on mutating routes (redirect for browsers, 403 with a redirect target for JSON) until they accept.
+
+## Caches
+
+Short TTLs everywhere; defaults below, environment variables may override per deploy:
+
+| Cache | Default |
+|-------|---------|
+| landing page | 30 s |
+| settings | 60 s |
+| version | 1 s |
+| unread counts | 10 s |
+| sitemap | 3600 s |
+| auth user lookups | 300 s |
+
+Docs prose is additionally cached in the process for its lifetime: doc text changes need a staging restart or a production rebuild to show.
+
+## Environments and data
+
+All runtime data lives under `./data/[env]` (database, blobs, backups, logs). Never anything outside it. Production data is holy: copies flow production to staging only, never back. Staging runs the dev server, so file changes show without restart except for the process-lifetime caches above. Production is a baked image and needs a rebuild for code, prose and media changes.
@@ -0,0 +1,24 @@
+<!-- retoor <retoor@molodetz.nl> -->
+{% extends "base.html" %}
+{% block content %}
+<header class="article-header">
+  <span class="label">Invite</span>
+  <h1>Accept your invite</h1>
+</header>
+{% if not valid %}
+<div class="notice error" role="alert"><ul>{% for error in errors %}<li>{{ error }}</li>{% endfor %}</ul></div>
+<p><a class="button ghost" href="/">Back home</a></p>
+{% else %}
+{% if errors %}
+<div class="notice error" role="alert"><ul>{% for error in errors %}<li>{{ error }}</li>{% endfor %}</ul></div>
+{% endif %}
+<form class="form" method="post">
+  <div class="field"><label for="username">Name</label><input id="username" type="text" name="username" required minlength="3" maxlength="32" pattern="[A-Za-z0-9_-]{3,32}" value="{{ (form or {}).username or '' }}" autocomplete="username"><p class="hint">3 to 32 letters, digits, _ or -.</p></div>
+  <div class="field"><label for="email">Email</label><input id="email" type="email" name="email" required maxlength="255" value="{{ (form or {}).email or '' }}" autocomplete="email"{% if email_locked %} readonly{% endif %}>{% if email_locked %}<p class="hint">This invite was issued for this address.</p>{% endif %}</div>
+  <div class="field"><label for="password">Password</label><input id="password" type="password" name="password" required minlength="6" maxlength="128" autocomplete="new-password"></div>
+  <div class="field"><label for="password_confirm">Password again</label><input id="password_confirm" type="password" name="password_confirm" required minlength="6" maxlength="128" autocomplete="new-password"></div>
+  <label class="check"><input type="checkbox" name="terms" value="true"> I accept the <a href="/terms" target="_blank" rel="noopener">house rules</a></label>
+  <div class="actions"><button class="button" type="submit" data-loading>Create my account</button></div>
+</form>
+{% endif %}
+{% endblock %}