funoteka 0.1.0

package/dist/api/genre.js

@@ -0,0 +1,81 @@
+import { childOf, required } from "./browse.js";
+import { ApiError, ERROR } from "./envelope.js";
+import { genres, songsByGenre } from "./meta.js";
+/**
+ * The genres, which are the one thing a Subsonic client asks for that this
+ * server had nothing to answer with.
+ *
+ * The meta layer has held them since the first scan — every file's `genre` tag
+ * is a row in `file_tag`, and there are 2338 of them over 159 values — but no
+ * route ever read one. A client asking `getGenres` was told the method did not
+ * exist and drew an empty list, which is what "the collection has no genres"
+ * looks like from the outside. It had them all along.
+ *
+ * There is no genre *table* here and this does not add one. A genre is what a
+ * file states, the same way a title is, and a table would be a second place for
+ * it to be true — with the first one still being the file. What is derived is
+ * the two counts a client wants beside each name, and they are derived on the
+ * request rather than stored.
+ */
+/** The protocol's own ceiling on a page, matching the album and song listings. */
+const MAX_PAGE = 500;
+/**
+ * How many songs `getSongsByGenre` returns when the client does not say.
+ *
+ * **The protocol's own number and its own parameter name**, which is `count` and
+ * not `size` — the sibling listing route uses `size`, and this method does not.
+ * The first version of this read `size` and defaulted to a hundred, which meant
+ * a client asking for `count=50` was quietly given whatever this server felt
+ * like: a caller who names an argument and is not obeyed has been lied to, and
+ * the lie is invisible from either side.
+ */
+const DEFAULT_COUNT = 10;
+function numeric(query, name, fallback) {
+    const raw = query.get(name);
+    if (raw === null || raw === '')
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value)) {
+        throw new ApiError(ERROR.generic, `${name} is not a whole number: ${raw}`);
+    }
+    return value;
+}
+/**
+ * Every genre the collection states, with how many songs and records state it.
+ *
+ * No paging, and no `size`/`offset` honoured: the protocol defines neither for
+ * this method, and a client shows the whole list in a sidebar. 159 entries is
+ * what this collection has; a list an order of magnitude larger would be a
+ * collection with a problem rather than this route's.
+ */
+export function getGenres(db, visibility = 'records') {
+    return {
+        genres: {
+            genre: genres(db, visibility).map((row) => ({
+                value: row.value,
+                songCount: row.song_count,
+                albumCount: row.album_count,
+            })),
+        },
+    };
+}
+/**
+ * The songs one genre names.
+ *
+ * The genre is taken as the file states it, trimmed the way the list trims it —
+ * so a client can hand back a value it was given and get the songs that value
+ * came from, which is the whole contract between these two methods.
+ */
+export function getSongsByGenre(db, query, visibility = 'records') {
+    const genre = required(query, 'genre');
+    // `count`, which is this method's own name for the argument — the sibling
+    // listing route calls it `size`, and a server that answered the wrong one
+    // would look to a client exactly like a server that ignored it.
+    const count = Math.min(Math.max(numeric(query, 'count', DEFAULT_COUNT), 1), MAX_PAGE);
+    const offset = Math.max(numeric(query, 'offset', 0), 0);
+    return {
+        songsByGenre: {
+            song: songsByGenre(db, genre, count, offset, visibility).map((row) => childOf(row)),
+        },
+    };
+}

package/dist/api/health.js

@@ -0,0 +1,35 @@
+import { SERVER_VERSION } from "./envelope.js";
+/** Seconds this process has been up, which is health's own business to report. */
+export const startedAgo = () => process.uptime();
+/**
+ * Read the meta layer and answer.
+ *
+ * A read that throws is the failure this route exists to catch, and it is
+ * answered rather than propagated: a database that has been replaced by a
+ * directory, a disk that has gone read-only, a file another process has locked
+ * for longer than a transaction should — each of them is a server that is *up*
+ * and cannot serve, which is a different state from "not running" and the one a
+ * supervisor must be told about.
+ *
+ * The schema version is read from the database rather than from the build's own
+ * constant: what a reader wants to know is what the *file* is at, and a build
+ * that expected a migration the file never got is exactly the mismatch this
+ * number makes visible.
+ */
+export function health(db, uptimeSeconds = startedAgo()) {
+    const base = {
+        server: 'funoteka',
+        version: SERVER_VERSION,
+        uptime: Math.round(uptimeSeconds * 10) / 10,
+    };
+    try {
+        const read = db.prepare('PRAGMA user_version').get();
+        return { status: 200, body: JSON.stringify({ status: 'ok', ...base, schema: read.user_version }) };
+    }
+    catch (err) {
+        return {
+            status: 503,
+            body: JSON.stringify({ status: 'failed', ...base, error: err.message }),
+        };
+    }
+}

package/dist/api/history.js

@@ -0,0 +1,374 @@
+import { markPlaying, nowPlaying, player, queue, recordPlay, saveQueue } from "../history/store.js";
+import { withTransaction } from "../db/index.js";
+import { childOf, ID, parseId, required } from "./browse.js";
+import { ApiError, ERROR } from "./envelope.js";
+import { knownTrackIds, song, songsByIds } from "./meta.js";
+/**
+ * What the listener played, what is playing, and the queue they left.
+ *
+ * The third set of routes that write — playlists first, then stars — and the
+ * same kind of thing: a statement about the music that no file states and no
+ * scan can rebuild. These go further than the other two in one way only: they
+ * are about *time*, so a row here says the collection was used rather than what
+ * somebody thought of it.
+ *
+ * The shapes are the protocol's, and several fields have no input parameter at
+ * all — `playerId`, `playerName` and `minutesAgo` are the server's to derive.
+ * Where that is so, the comment below says what it was derived from and why,
+ * because a client cannot be told apart from another except by the name it gave.
+ */
+/** How a client names itself. The protocol's `c`, and the only identity there is. */
+function clientOf(query) {
+    return query.get('c') ?? '';
+}
+/**
+ * The track an id names, or a refusal.
+ *
+ * `scrobble`, `savePlayQueue` and the rest all take ids that name *songs*, so a
+ * `al:` or a `pl:` is not a narrower answer — it is a client asking the wrong
+ * question, and saying "no such id" is truer than answering about an album.
+ */
+function trackOf(db, raw) {
+    const parsed = parseId(raw);
+    const found = parsed !== undefined && parsed.kind === 'tr' ? song(db, parsed.n) : undefined;
+    if (found === undefined)
+        throw new ApiError(ERROR.notFound, `No such id: ${raw}`);
+    return found.id;
+}
+/** Every `id` the request repeated, in the order it was given, empty ones dropped. */
+function ids(query) {
+    return query.getAll('id').filter((raw) => raw !== '');
+}
+/**
+ * The tracks a request named, resolved for the whole call rather than per id.
+ *
+ * `trackOf` answers with a whole `SongRow` — a `SONG_SELECT`, with the
+ * album-groups subquery materialized inside it — and the write paths need
+ * nothing from it but the id. Measured on the live daemon: a six-hundred-id
+ * `scrobble` paid that select six hundred times, took **1122–1243 ms**, and a
+ * `ping` sent during it waited **1133 ms** against 1.8 ms idle. On one thread
+ * that is not a slow handler, it is every other client stopped for a second —
+ * and the two calls that take a list are the two a client makes with one:
+ * finishing an album, uploading a day of offline listening, saving a queue.
+ *
+ * `knownTrackIds` answers the same question in one statement per five hundred
+ * ids — measured at **1.3 ms for six hundred** — which is what `playlist.ts`
+ * does for its own ids and for this reason.
+ *
+ * Order and duplicates are kept. The last id is what a scrobble leaves playing,
+ * and a queue may hold the same song at two seats; a set would lose both.
+ */
+function tracksOf(db, raw) {
+    const parsed = raw.map((one) => {
+        const id = parseId(one);
+        if (id === undefined || id.kind !== 'tr') {
+            throw new ApiError(ERROR.notFound, `No such id: ${one}`);
+        }
+        return id.n;
+    });
+    const known = knownTrackIds(db, parsed);
+    return parsed.map((id, at) => {
+        if (!known.has(id))
+            throw new ApiError(ERROR.notFound, `No such id: ${raw[at]}`);
+        return id;
+    });
+}
+/** How long ago, in whole minutes, as the protocol counts it. */
+function minutesAgo(from, now) {
+    // Floored, not rounded: "last update" is time *elapsed*, and a track thirty
+    // seconds in is nought minutes old — reporting it as one would say a client
+    // had been playing something it had only just started.
+    return Math.max(0, Math.floor((now.getTime() - new Date(from).getTime()) / 60_000));
+}
+/**
+ * Register a play, or that one is happening.
+ *
+ * **Both kinds update what is playing**, and only one writes a play. The
+ * protocol's own description of this method is what settles it — a scrobble
+ * "makes the media files appear in the Now playing page … and appear in the list
+ * of songs returned by `getNowPlaying`" — while `submission=false` is the
+ * narrower notification a client sends as a track *starts*. So the two differ in
+ * whether a play is recorded, and not in whether the client is shown as playing:
+ * a client that only ever sends submissions is still shown, which is what the
+ * bullet above promises it.
+ *
+ * An id that names nothing refuses the whole call before anything is written —
+ * `trackOf` throws while the list is still being built — so a batch of forty
+ * songs written one at a time cannot leave thirty-nine of them behind.
+ *
+ * **`time` is read, per id.** The protocol pairs it with `id` one for one
+ * ("Since 1.8.0 you may specify multiple `id` (and optionally `time`)
+ * parameters"), and it is the only thing that dates a play made while the client
+ * was offline — which is the case the playback-report extension names. An id
+ * whose `time` is absent, unreadable or missing is stamped with the moment the
+ * server was told, which is what every play was stamped with before this.
+ */
+export function scrobble(db, query) {
+    const named = ids(query);
+    if (named.length === 0)
+        required(query, 'id');
+    const trackIds = tracksOf(db, named);
+    const submission = query.get('submission') !== 'false';
+    const at = new Date();
+    const times = query.getAll('time');
+    withTransaction(db, () => {
+        // Inside the transaction with everything else: `player` is a read and a
+        // possible insert, and its twin in `playlist/store.ts` documents why that
+        // pair has to be one atomic step.
+        const who = player(db, clientOf(query));
+        if (submission) {
+            recordPlay(db, who, trackIds.map((trackId, index) => ({ trackId, at: playTime(times[index], at) })));
+        }
+        // The last one named: a client finishing an album is the ordinary batch, and
+        // the track it finished on is the one that was playing.
+        markPlaying(db, who, trackIds[trackIds.length - 1], at.toISOString());
+    });
+    return {};
+}
+/** The client's `time` for one play, or the moment the server was told. */
+function playTime(raw, at) {
+    if (raw === undefined || raw === '')
+        return at.toISOString();
+    const ms = Number(raw);
+    return Number.isFinite(ms) ? new Date(ms).toISOString() : at.toISOString();
+}
+/**
+ * What every client is playing, and how far in.
+ *
+ * `minutesAgo` is the whole of what tells a reader whether an entry is live:
+ * this server does not expire one, because the protocol leaves the judgement to
+ * whoever reads the list and any timeout would be a rule about how long a track
+ * is that no client agreed to. `now` is taken once for the whole answer so two
+ * entries updated in the same second cannot disagree by a minute, and it is a
+ * seam because that is the only way a test can ask about an entry that is not
+ * brand new.
+ */
+export function getNowPlaying(db, config, now = () => new Date()) {
+    const rows = nowPlaying(db);
+    const songs = songsByIds(db, rows.map((row) => row.trackId));
+    const byId = new Map(songs.map((row) => [row.id, row]));
+    const at = now();
+    const entry = rows.flatMap((row) => {
+        const found = byId.get(row.trackId);
+        if (found === undefined)
+            return [];
+        return [
+            {
+                ...childOf(found),
+                username: config.user,
+                minutesAgo: minutesAgo(row.updatedAt, at),
+                playerId: row.playerId,
+                // Absent rather than empty when the client named itself after nothing:
+                // a `playerName` of `""` is a player whose name is nothing, and one that
+                // is not there is a player nobody named.
+                ...(row.playerName === '' ? {} : { playerName: row.playerName }),
+                ...(row.state === null ? {} : { state: row.state }),
+                ...(row.positionMs === null ? {} : { positionMs: row.positionMs }),
+                ...(row.playbackRate === null ? {} : { playbackRate: row.playbackRate }),
+            },
+        ];
+    });
+    return { nowPlaying: { entry } };
+}
+/**
+ * Where a player is in a track, as the `playbackReport` extension reports it.
+ *
+ * **This server keeps the state and does not scrobble from it.** The extension
+ * asks a server to record a play once the media reaches a `stopped` state, and
+ * that is a rule this server has not decided: "was it played" is a policy — half
+ * the track, four minutes, whatever a person means by having listened — and the
+ * clients here already say it themselves through `scrobble`, which is the method
+ * the protocol provides for it. So `state` and `positionMs` are remembered and
+ * reported back by `getNowPlaying` to a *different* client, which is what this
+ * extension is for, and no play is written here.
+ *
+ * `ignoreScrobble` is therefore accepted and has nothing to suppress. It is not
+ * ignored in the sense of being unimplemented — there is no scrobble on this
+ * path for it to prevent — and that is said here rather than left for whoever
+ * wonders why the parameter changes nothing.
+ */
+export function reportPlayback(db, query) {
+    const mediaId = required(query, 'mediaId');
+    // `mediaType` is required by the extension, so an absent one is a missing
+    // parameter and not a bad value — the two are answered differently on purpose
+    // (`ERROR.missingParameter` against `ERROR.generic`), and a client that forgot
+    // it should be told it forgot rather than that it sent the wrong thing.
+    const mediaType = required(query, 'mediaType');
+    if (mediaType !== 'song') {
+        throw new ApiError(ERROR.generic, `mediaType is not a song this server holds: ${mediaType} (it has no podcasts)`);
+    }
+    const rawPosition = required(query, 'positionMs');
+    const positionMs = Number(rawPosition);
+    if (!Number.isFinite(positionMs) || positionMs < 0) {
+        throw new ApiError(ERROR.generic, `positionMs is not a position: ${rawPosition}`);
+    }
+    const state = required(query, 'state');
+    if (!STATES.has(state)) {
+        throw new ApiError(ERROR.generic, `state is not one of ${[...STATES].join(', ')}: ${state}`);
+    }
+    const rawRate = query.get('playbackRate');
+    const rate = rawRate === null || rawRate === '' ? 1 : Number(rawRate);
+    if (!Number.isFinite(rate) || rate <= 0) {
+        throw new ApiError(ERROR.generic, `playbackRate is not a speed: ${rawRate ?? ''}`);
+    }
+    const trackId = trackOf(db, mediaId);
+    withTransaction(db, () => {
+        markPlaying(db, player(db, clientOf(query)), trackId, new Date().toISOString(), {
+            state,
+            positionMs,
+            playbackRate: rate,
+        });
+    });
+    return {};
+}
+const STATES = new Set(['starting', 'playing', 'paused', 'stopped']);
+/**
+ * The seat the current track occupies, from the id a client can also use.
+ *
+ * The older endpoint addresses the current track by id and the `indexBasedQueue`
+ * extension by seat, and both read the same queue — the extension exists because
+ * an id cannot say *which* of two identical entries is playing, not to keep a
+ * second list. So a save by id finds the seat here, and a save by seat uses it
+ * as given.
+ *
+ * The *first* matching seat wins, which is the only answer an id can give when
+ * the queue holds the same song twice; a client that means the second one says
+ * so with the endpoint that can.
+ */
+function seatOfTrack(entries, trackId, raw) {
+    const found = entries.find((entry) => entry.trackId === trackId);
+    if (found === undefined) {
+        throw new ApiError(ERROR.generic, `current is not in the queue: ${raw}`);
+    }
+    return found.position;
+}
+/** The `position` parameter, which the protocol says to read as zero when absent. */
+function positionOf(query) {
+    const raw = query.get('position');
+    if (raw === null || raw === '')
+        return 0;
+    const position = Number(raw);
+    if (!Number.isFinite(position) || position < 0) {
+        throw new ApiError(ERROR.generic, `position is not a position: ${raw}`);
+    }
+    return position;
+}
+/**
+ * The two saves, which differ only in how the current track is named.
+ *
+ * `id` is optional in both — OpenSubsonic's change — and a call with none is how
+ * a client says "forget this queue": the whole queue is cleared and `changedBy`
+ * still says who cleared it. `currentIndex` is *not* read on that path, because
+ * the specification forbids it: "Send a call without any parameters to clear the
+ * currently saved queue. In this case, `currentIndex` **must not** be set." A
+ * call that sets it anyway is a client that has confused the two endpoints, and
+ * clearing its queue in silence is the one answer that would hide that.
+ */
+function save(db, query, byIndex) {
+    const named = ids(query);
+    const at = new Date().toISOString();
+    const changedBy = clientOf(query);
+    if (named.length === 0) {
+        const stray = query.get('currentIndex');
+        if (stray !== null && stray !== '') {
+            throw new ApiError(ERROR.missingParameter, `currentIndex names a track in a queue that was not sent: ${stray} (send no id to clear)`);
+        }
+        saveQueue(db, { trackIds: [], currentPosition: null, positionMs: 0, changedBy }, at);
+        return {};
+    }
+    const trackIds = tracksOf(db, named);
+    const positionMs = positionOf(query);
+    let currentPosition;
+    if (byIndex) {
+        const raw = required(query, 'currentIndex');
+        // Code 10 by the specification's own words: "if `currentIndex` is not
+        // between 0 and length of the queue - 1 (inclusive), the server must respond
+        // with error code 10" — which is this protocol's name for a parameter that
+        // cannot be used, whatever the reason it cannot be.
+        const index = Number(raw);
+        if (!Number.isInteger(index) || index < 0 || index >= trackIds.length) {
+            throw new ApiError(ERROR.missingParameter, `currentIndex is not a position in the queue: ${raw} (0..${trackIds.length - 1})`);
+        }
+        currentPosition = index;
+    }
+    else {
+        const raw = required(query, 'current');
+        currentPosition = seatOfTrack(trackIds.map((trackId, position) => ({ position, trackId })), trackOf(db, raw), raw);
+    }
+    saveQueue(db, { trackIds, currentPosition, positionMs, changedBy }, at);
+    return {};
+}
+export function savePlayQueue(db, query) {
+    return save(db, query, false);
+}
+export function savePlayQueueByIndex(db, query) {
+    return save(db, query, true);
+}
+/**
+ * Where in the surviving seats the current one is.
+ *
+ * The stored number is a *seat*, and a sweep that takes a queued track away
+ * leaves the seat unused rather than moving the ones after it. So the current
+ * track is found by its number and not by counting from the front — and when the
+ * seat itself is gone, the queue has moved on, so the answer is the next seat
+ * along and the last one when there is no next.
+ *
+ * The protocol requires a current track to be named whenever the queue is not
+ * empty ("OpenSubsonic servers must ensure that `current` exists and is a valid
+ * id in the list of songs"), which is why this never answers "none" while there
+ * is something to point at.
+ */
+function currentSeat(entries, seat) {
+    const exact = entries.findIndex((entry) => entry.position === seat);
+    if (exact !== -1)
+        return exact;
+    const next = entries.findIndex((entry) => entry.position > seat);
+    return next === -1 ? entries.length - 1 : next;
+}
+/**
+ * The queue, answered the two ways its two endpoints ask.
+ *
+ * `changed` and `changedBy` are the protocol's required fields, and they are
+ * absent in exactly one case: no queue has ever been saved. The specification's
+ * list of required fields describes a queue, and before the first save there is
+ * none to describe — so the answer names the user, carries no entries, and says
+ * nothing about who last changed a thing that has never changed. A queue that
+ * was saved and then emptied *does* carry them, which is the difference between
+ * "nobody has ever queued anything" and "this client cleared the queue", and a
+ * client syncing between devices wants to tell those apart.
+ */
+function read(db, config, byIndex) {
+    const saved = queue(db);
+    const rows = saved === null ? [] : songsByIds(db, saved.entries.map((entry) => entry.trackId));
+    const byId = new Map(rows.map((row) => [row.id, row]));
+    // Every seat has its track: `play_queue_entry` cascades, so a swept track took
+    // its seat with it. The order is the seats' own, which is the order they were
+    // saved in.
+    const entries = (saved?.entries ?? []).map((entry) => childOf(byId.get(entry.trackId)));
+    const seat = saved === null || saved.currentPosition === null || entries.length === 0
+        ? null
+        : currentSeat(saved.entries, saved.currentPosition);
+    const current = seat === null ? undefined : ID.track(saved.entries[seat]?.trackId);
+    const body = {
+        username: config.user,
+        ...(saved === null ? {} : { changed: saved.changedAt, changedBy: saved.changedBy }),
+        ...(current === undefined ? {} : { current }),
+        position: saved?.positionMs ?? 0,
+        entry: entries,
+    };
+    if (!byIndex)
+        return { playQueue: body };
+    // The extension's own shape: the same queue, addressed by seat, and the id
+    // left out — a client that asked ByIndex has said it does not want to be told
+    // which id is playing, because an id cannot tell two equal entries apart.
+    const { current: _ignored, ...byIndexBody } = body;
+    return {
+        playQueueByIndex: { ...byIndexBody, ...(seat === null ? {} : { currentIndex: seat }) },
+    };
+}
+export function getPlayQueue(db, config) {
+    return read(db, config, false);
+}
+export function getPlayQueueByIndex(db, config) {
+    return read(db, config, true);
+}

package/dist/api/idempotency.js

@@ -0,0 +1,66 @@
+/**
+ * The same request, made twice, answered once.
+ *
+ * A control surface is called by scripts and agents over a network, and a
+ * network offers two failures that look identical from the caller's side: the
+ * request that never arrived, and the answer that was lost coming back. A caller
+ * that retries cannot tell them apart — and for a mutation it must, because
+ * doing the work twice is not the same as doing it once. `Idempotency-Key` is
+ * the caller saying "this is the same request"; this is where the first answer
+ * waits so that the second one can be given it.
+ *
+ * **Kept in the database, because `POST /restart` is in this surface.** An
+ * in-memory map would be cleared by the very operation a client is most likely
+ * to be retrying across — the server restarts, the client's connection drops,
+ * the client retries, and the process that knew the key is gone. The record has
+ * to outlive the thing it was protecting.
+ *
+ * What a key is *for* is checked as well as what it answered: the same key on a
+ * different method or path is a caller that reused one by mistake, and answering
+ * it with another operation's result would be the worst possible behaviour —
+ * silently correct-looking and about something else.
+ */
+/**
+ * How long an answer stays replayable.
+ *
+ * A day, because the window this exists for is one client's retry after a
+ * dropped connection — seconds to minutes — and the reason to bound it is that
+ * the table would otherwise grow for ever with keys nobody will ask about again.
+ */
+export const KEEP_MS = 24 * 60 * 60 * 1000;
+/**
+ * What this key answered before, if anything.
+ *
+ * An empty key is not a key: a caller that sent none is asking for the ordinary
+ * behaviour, and treating `''` as a value would make every such request share
+ * one record.
+ */
+export function recall(db, key, method, path) {
+    if (key === '')
+        return { kind: 'fresh' };
+    const row = db
+        .prepare('SELECT method, path, status, body FROM admin_idempotency WHERE key = ?')
+        .get(key);
+    if (row === undefined)
+        return { kind: 'fresh' };
+    const recorded = { status: row.status, body: row.body };
+    if (row.method !== method || row.path !== path)
+        return { kind: 'conflict', recorded };
+    return { kind: 'replay', recorded };
+}
+/**
+ * Keep this answer for this key.
+ *
+ * `INSERT OR REPLACE` rather than a plain insert: two callers racing with one
+ * key is not an error to report, it is the case this exists for, and whoever
+ * gets there second overwrites an answer that is about to be read back as the
+ * same answer anyway. Pruning runs here rather than on a timer, because this is
+ * the only moment the table grows.
+ */
+export function remember(db, key, method, path, status, body, now = Date.now()) {
+    if (key === '')
+        return;
+    db.prepare('INSERT OR REPLACE INTO admin_idempotency (key, method, path, status, body, created_at) ' +
+        'VALUES (?, ?, ?, ?, ?, ?)').run(key, method, path, status, body, new Date(now).toISOString());
+    db.prepare('DELETE FROM admin_idempotency WHERE created_at < ?').run(new Date(now - KEEP_MS).toISOString());
+}

package/dist/api/keys.js

@@ -0,0 +1,90 @@
+import { randomBytes } from 'node:crypto';
+import { sameSecret } from "./auth.js";
+/**
+ * A secret for a new key, from the operating system's random source.
+ *
+ * 32 bytes, hex: the same shape as the environment key this project already
+ * uses, so that anything which accepts one accepts the other, and long enough
+ * that guessing it is not a thing anyone tries twice.
+ */
+export function newSecret() {
+    return randomBytes(32).toString('hex');
+}
+/**
+ * Whether a presented key is one of the registered ones.
+ *
+ * **Every active row is compared, rather than looked up by value.** A `WHERE
+ * secret = ?` would be an index probe whose duration says how nearly the guess
+ * matched, which is the same leak `sameSecret` exists to close on the password;
+ * a registry of keys is small enough that comparing all of them is free. Revoked
+ * rows are left out — they are kept for the record, not honoured.
+ */
+export function keyHolds(db, given) {
+    const rows = db.prepare('SELECT secret FROM api_key WHERE revoked_at IS NULL').all();
+    return rows.some((row) => sameSecret(given, row.secret));
+}
+/**
+ * Register a key under a label, and answer with the row that was written.
+ *
+ * A secret may be given rather than generated, because a person moving their
+ * setup may want the key they already have — but a secret this table has ever
+ * held is refused, revoked or not. Silently accepting one would resurrect a key
+ * somebody had deliberately taken back.
+ */
+export function addKey(db, label, secret = newSecret(), now = new Date()) {
+    const trimmed = label.trim();
+    if (trimmed === '')
+        throw new Error('a key needs a label — what it is for, or whose it is');
+    if (secret.trim() === '')
+        throw new Error('a key needs a secret');
+    const seen = db.prepare('SELECT revoked_at FROM api_key WHERE secret = ?').get(secret);
+    if (seen !== undefined) {
+        throw new Error(seen.revoked_at === null
+            ? 'that secret is already registered to an active key'
+            : `that secret was revoked on ${seen.revoked_at} and is not given out again`);
+    }
+    const createdAt = now.toISOString();
+    db.prepare('INSERT INTO api_key (label, secret, created_at) VALUES (?, ?, ?)').run(trimmed, secret, createdAt);
+    const written = db.prepare('SELECT id FROM api_key WHERE secret = ?').get(secret);
+    return { id: written.id, label: trimmed, secret, createdAt, revokedAt: null };
+}
+/** Every key the table has ever held, newest first, revoked ones included. */
+export function listKeys(db) {
+    const rows = db
+        .prepare(`SELECT id, label, secret, created_at AS createdAt, revoked_at AS revokedAt
+       FROM api_key ORDER BY created_at DESC, id DESC`)
+        .all();
+    return rows;
+}
+/**
+ * Take a key back, by id or by the label it was given.
+ *
+ * Refuses rather than answering quietly when it matches nothing or matches
+ * more than one: `revoke tablet` with two keys called "tablet" would take back
+ * a key the person did not name, and this is the one operation where being
+ * wrong is invisible until a device stops working.
+ */
+export function revokeKey(db, idOrLabel, now = new Date()) {
+    // **`#3` is a form this has to accept, because it is the form this prints.**
+    // `keys list` shows `#3  the tablet`, the ambiguity refusal below says "name
+    // one by number: #12 (label)", and the usage line offers `<label|#id>` — and
+    // `Number('#3')` is `NaN`, so the one spelling the CLI advertised was the one
+    // it could not read. Found independently by two axes of the review umbrella,
+    // which is what a spelling nobody tested looks like from both sides
+    // (task:2924).
+    const named = idOrLabel.startsWith('#') ? idOrLabel.slice(1) : idOrLabel;
+    const asId = Number(named);
+    const rows = db
+        .prepare(`SELECT id, label, secret, created_at AS createdAt, revoked_at AS revokedAt
+       FROM api_key WHERE revoked_at IS NULL AND (label = ? OR id = ?)`)
+        .all(idOrLabel, Number.isInteger(asId) ? asId : -1);
+    if (rows.length === 0)
+        throw new Error(`no active key called or numbered "${idOrLabel}"`);
+    if (rows.length > 1) {
+        throw new Error(`${rows.length} active keys match "${idOrLabel}" — name one by number: ` +
+            rows.map((row) => `#${row.id} (${row.label})`).join(', '));
+    }
+    const revokedAt = now.toISOString();
+    db.prepare('UPDATE api_key SET revoked_at = ? WHERE id = ?').run(revokedAt, rows[0].id);
+    return { ...rows[0], revokedAt };
+}