bookshelf/server/README.md

# Bookshelf server

PocketBase backend for the Bookshelf app — see `../docs/SPEC.md` for the
authoritative data model and API rules. This directory contains everything
needed to provision and run it.

## Layout

```
server/
  pocketbase          PocketBase v0.40.2 binary (gitignored — platform-specific)
  pb_data/            SQLite databases + uploaded files (gitignored — runtime state)
  pb_migrations/       Schema history, auto-captured — a fresh instance replays
                       these on first boot and ends up with the full schema
  pb_hooks/           JS hook that closes a PocketBase quirk (see below)
  setup-schema.sh     Idempotent schema/rules provisioning (curl + jq only)
  create-user.sh      Superuser-driven account creation (no public sign-up)
  deploy/             systemd unit, Docker, backups, remote-access guidance
```

## Quickstart (local dev)

PocketBase must already be running (see `deploy/README.md` for how to run
it as a proper service; for a quick local check you can just run the binary
directly: `./pocketbase serve`).

```sh
# 1. Provision the schema + API rules (safe to re-run).
./setup-schema.sh http://127.0.0.1:8090 <superuser-email> <superuser-password>

# 2. Create app accounts — there is no self-registration.
./create-user.sh you@example.com "a strong password" "Your Name"
```

Both scripts also read `PB_URL`/`PB_EMAIL`/`PB_PASS` from the environment,
or fall back to `.dev-credentials` (gitignored, dev-instance-only — see
`.dev-credentials` in this directory if present) if no args are given.

## Schema summary

Three collections — `bookcases`, `shelves`, `books` — each requiring
authentication for every action (list/view/create/update/delete). Deletion
in the app is always a soft `deleted` flag (tombstone), never an actual
record delete, so sync can propagate it — see `SyncEngine` in the Android
app and `docs/SPEC.md`'s Sync design section.

The built-in `users` collection is locked down: `createRule = null` means
**only a superuser can create an account** (via `create-user.sh`); regular
users can view any user (needed to resolve the `added_by` relation) and
update only their own record.

## The pb_hooks quirk

PocketBase's declarative list/search rule acts as a row-level SQL filter,
not a hard gate: an unauthenticated request against a collection whose
`listRule` requires auth still gets **`200 OK` with an empty result**,
rather than an error — because the rule can't be cleanly separated into
"deny the whole request" vs. "just don't return matching rows" (see
[pocketbase/pocketbase#6492](https://github.com/pocketbase/pocketbase/discussions/6492)).
No private data ever leaks this way, but a `200` is still the wrong signal
for "you're not allowed here." `pb_hooks/main.pb.js` adds a small
`onRecordsListRequest` hook that turns that into a `403` for the three app
collections. It's plain JS, auto-loaded by the stock `pocketbase` binary —
no recompilation, no framework — so it ships and deploys exactly like
`pb_migrations/`.

## Verifying a deployment

**Run these against the address the outside world uses, not `127.0.0.1`.**
A localhost curl cannot tell you what is reachable from the internet, and
the live instance of this server (see below) *is* on the internet, with
these rules as its only protection.

```sh
BASE=https://your-server.example        # the PUBLIC base URL, not localhost

# Anonymous requests must be rejected for all three collections:
for c in books shelves bookcases; do
  curl -s -o /dev/null -w "$c %{http_code}\n" "$BASE/api/collections/$c/records"
done
# -> 403, 403, 403

# Self-registration must be rejected:
curl -s -X POST "$BASE/api/collections/users/records" \
  -H 'Content-Type: application/json' -d '{"email":"x@x.com","password":"password123","passwordConfirm":"password123"}'
# -> 403 "Only superusers can perform this action."
```

A `200` with a non-empty `items` array from any of those is a breach, and a
`200` with an empty one means the `pb_hooks` guard is not loaded — see the
quirk described above.

> **Known gap:** `GET /api/collections/users/records` currently answers
> **200 with an empty array** rather than 403. Nothing is disclosed — the
> `listRule` filters every row out, so an anonymous caller sees no accounts,
> no emails, no ids — but it is the same wrong-signal quirk as above, and
> `pb_hooks/main.pb.js` does not yet cover the `users` collection. Adding it
> to that hook's collection list closes it.

## Where the live server runs

The instance these phones talk to runs **on the development sprite**, bound
to `0.0.0.0:8090` and published over HTTPS on a sprite-issued hostname, so
it is **internet-exposed**. That is an interim arrangement; `deploy/` covers
the intended move to home hardware behind Tailscale. The app never hardcodes
a server URL — it is entered on the first-run setup screen — so that move
needs no code change, only re-pointing each phone.

See `deploy/README.md` for running the server long-term, reaching it from
outside your home network, and backups.