@acornly/adapter-firebase 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Free Solo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @acornly/adapter-firebase
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A `StorageAdapter` that keeps Acornly notes in a site's own Firestore, with no Acornly Cloud involved. The site pays its own Firebase bill and Acornly charges nothing.
+
+The adapter reads and writes as whoever is signed in on the site's Firebase Auth, or as a visitor when nobody is. The Firestore security rules this package ships decide what each of them may see and change.
+
+## Set up Firebase
+
+1. Deploy the rules and indexes that ship in the package, [`firestore.rules`](firestore.rules) and [`firestore.indexes.json`](firestore.indexes.json) (also under `node_modules/@acornly/adapter-firebase/`). If the site has no rules of its own, point `firebase.json` at them and run `firebase deploy --only firestore`:
+
+   ```json
+   {
+     "firestore": {
+       "rules": "node_modules/@acornly/adapter-firebase/firestore.rules",
+       "indexes": "node_modules/@acornly/adapter-firebase/firestore.indexes.json"
+     }
+   }
+   ```
+
+   If it has, copy the functions and the `acornly_` matches into its rules file, and the indexes into its indexes file. Everything they cover is in collections prefixed with `acornly_`.
+
+2. List the scopes the site accepts notes in, as documents in `acornly_scopes` whose id is the scope. Signed-in users can write only to these, plus their own `user:<uid>` scope. Clients cannot write this collection, so add them in the Firebase console or with the Admin SDK:
+
+   ```ts
+   await admin.firestore().doc("acornly_scopes/app:my-site").set({});
+   // Let visitors who are not signed in read the public notes in this scope:
+   await admin.firestore().doc("acornly_scopes/web:example.com").set({ anonymousRead: true });
+   ```
+
+3. Turn on a sign-in method in Firebase Authentication. Notes are written as the signed-in Firebase user, and anonymous sign-ins cannot write.
+
+## Use it
+
+```ts
+import { initializeApp } from "firebase/app";
+import { getAuth } from "firebase/auth";
+import { getFirestore } from "firebase/firestore";
+import { FirebaseAdapter } from "@acornly/adapter-firebase";
+
+const app = initializeApp(firebaseConfig);
+const adapter = new FirebaseAdapter({ firestore: getFirestore(app), auth: getAuth(app) });
+```
+
+`firebase` 12 or later in 12.x is a peer dependency: the adapter uses the site's app and adds nothing to the bundle for it.
+
+## Access rules
+
+| Who                            | Can read                                      | Can write                                                                   |
+| ------------------------------ | --------------------------------------------- | --------------------------------------------------------------------------- |
+| The note's creator             | Their own notes, always                       | Edit or remove their own notes, in listed scopes or their own `user:` scope |
+| Anyone signed in               | `public` notes                                | New notes in listed scopes and their own `user:` scope                      |
+| A visitor who is not signed in | `public` notes in scopes with `anonymousRead` | Nothing                                                                     |
+| The site's server (Admin SDK)  | Everything (security rules do not apply)      | Anything, so it must keep the fields below consistent itself                |
+
+- Firebase's anonymous sign-ins count as visitors who are not signed in, although they have a user id.
+- Two audiences are supported: `private` (only the creator) and `public`. Circles, user lists and links need Acornly Cloud and are refused.
+- Each note is one document in `acornly_annotations`, named by the note's id. Ids are 1 to 128 letters, digits, `_`, `~` or `-` (Acornly's are ULIDs), so a reply's target IRI holds its parent's id unescaped. Notes imported from W3C files keep their ids, so an import whose ids are IRIs (such as Hypothesis URLs) is refused here; give such notes new ids first.
+- The document holds the annotation as JSON (`json`, up to 64 KB) and, beside it, the fields the rules check: the author's `uid`, `creatorId`, `scope`, `source` (`target.source`, or for a note on a PDF the file's key in `ext.documentKey`, which the JSON's `target.source` then leaves as the URL the note was made on), `parent`, `threadRoot`, `depth`, `parentRev`, `audience`, `modified`, `rev` and `deleted`. When the adapter reads a note, those fields take precedence over the JSON's copy of them, so nobody can make a note look like it is somewhere or for someone it is not. The rest of the annotation is stored as sent, so validate notes from other users before trusting their shape. A document whose JSON is not an object with `target` and `ext` is skipped.
+- Scopes are `app:`, `web:` or `user:` followed by anything but `/`. `modified` is an ISO 8601 time with a `Z` or an offset.
+- `uid` is the signed-in user who created the note, checked by the rules. Show that as the author: the annotation's own `creator` field is whatever the client sent.
+- `rev` is checked by the rules: a note starts at 1 and each update adds one. Every write is a Firestore transaction that reads the note first, so of two concurrent edits one wins and the other gets a `ConflictError`.
+- Context on context (replies, tags, reactions, highlights on a note) targets its parent: `target.source` is `urn:contexthive:annotation:<parent id>`, and it carries `ext.threadRoot` and `ext.depth`. Add it with `adapter.threads.addChild` (or core's `addContext`). The rules check it against the stored parent: the parent must exist, be readable by the replier and not be deleted, and the child must have its scope, thread root, the next depth, and a parent rev the parent has had. The rules cannot see quotes inside the JSON, so only the adapter checks that `ext.parentRev` is set exactly when the child quotes its parent. A child can narrow its parent's audience (a private reply under a public note) but never widen it, on create or on edit. Children nest to any depth.
+- Each note keeps the ids of its direct children in `kids`, changed only in the same write that adds or removes that child, which the rules check. That is how a delete knows a note still has children, even ones the deleter cannot read. It also means anyone who can read a note can read the ids of all its direct children, private ones included, and ULIDs carry their creation time: a private reply's existence and time are not secret, only its content and author.
+- Plain updates keep the tree: no note moves to another scope, document or thread (a note on a PDF keeps its `ext.documentKey`, whatever the update says), `ext.depth`, `ext.parentRev` and the target stay, `ext.deleted` changes only through a delete, a deleted placeholder cannot be edited, and a note with replies keeps its `creator.id`. Plain removes refuse replies and notes with replies; the rules refuse removing a note that has children from any client.
+- Delete with `adapter.threads.deleteNode` (or core's `deleteContext`). Only the author can delete a note (and anyone signed in can remove a placeholder with no children left). One with any reply, even one the author cannot see, becomes a placeholder: no body, author name or edited mark, `ext.deleted: true`. One without replies is removed, and so is each placeholder above it left with none, whoever wrote it: the rules let anyone remove a placeholder whose last child goes in the same write. A long chain of placeholders goes six at a time, each step its own transaction, since Firestore allows the rules of one write 20 document lookups; should a later step fail, the placeholders it leaves have no children and readers never see them.
+- **Replies under a narrowed note stay readable.** Firestore rules check each note on its own and cannot follow a reply's parents, so when a note is narrowed from public to private, other people's public replies below it stay readable to anyone signed in who asks for them, by id or by loading the thread. Core's `assembleThread`, which the SDK and the built-in UI use, hides them; the private note itself stays private. Delete or narrow such replies when that is not enough.
+- Edit history lives in `acornly_versions` (`adapter.versions`), one document per note holding its saved versions. Only the note's author can save, read or clear them; removing a note or turning it into a placeholder drops them. A Firestore document holds 1 MiB, so when a note's versions outgrow that, the oldest are dropped.
+- Deleting a Firebase Auth user leaves their notes. Remove them from the site's server with the Admin SDK, which the rules do not check: delete a user's notes without replies, and turn ones with replies into placeholders, taking each removed note out of its parent's `kids`.
+- `modified` comes from the client and is what `list({ since })` compares, so a client with a wrong clock (or one that writes a time far ahead) can make its edit invisible, or always present, to other clients' delta syncs. Treat delta sync as a shortcut and resync with a full `list` now and then.
+- Ids are chosen by the client, so creating an id that already exists fails even when the existing note is hidden. Use random ids (Acornly's are ULIDs) so this reveals nothing. Reading an id behaves the same way: Firestore refuses a hidden note but reports a missing one as missing, so a probe can tell that a hidden id exists.
+- Edits need the scope to still be listed (or be the author's own `user:` scope), as on Supabase; deletes do not, so a delisted scope's notes can still be removed by their authors.
+- A parent's `kids` lives in its document, which Firestore caps at 1 MiB: a note can take tens of thousands of direct children, not more.
+- Each reply, tag or reaction also writes its parent's document (its `kids`). Firestore sustains about one write a second to one document and a transaction gives up after five retries, so a burst of reactions on one note can fail some of them.
+- Writes need a connection: Firestore transactions fail offline, whatever the site's cache settings.
+
+## What it costs
+
+Firestore bills each document a query returns or a rule looks up, not each request, so a page's notes cost reads in proportion to how many there are:
+
+- `list` runs two queries for someone signed in (public notes, and their own) and one for a visitor, and is billed one read per note returned, at least one per query. A delta sync (`since`) reads only the notes changed since.
+- Loading a thread reads its root and every node in it. Counting replies (`threads.countChildren`) reads each parent and runs two count queries, billed one read per 1,000 replies counted.
+- `subscribe` keeps two snapshot listeners open per page, billed one read per note when they start and one per note changed while they run. A listener that reconnects after being offline for more than 30 minutes is billed as if it started again.
+- Each write is a transaction that reads the note (and a reply's parent, a delete's placeholders above it), and the rules' lookups of other documents are billed as reads too: a few per write.
+
+A page with many notes and many visitors can add up. Firestore's own usage tab shows the reads; budget alerts in the Google Cloud console warn before a bill grows.
+
+## Live updates
+
+`subscribe` listens to Firestore snapshots of the page's public notes and of the caller's own notes, which the same rules filter. A subscriber hears about its own adapter's writes at once and does not hear them again when the snapshot echoes them. Unlike Supabase Realtime, a note narrowed from public to private, or deleted, is told to other readers as removed.
+
+- **Replies are not followed.** A subscription follows one page, and replies target their parent rather than the page, so subscribers hear about a note turning into a placeholder but not about replies being added or edited. Load threads with `threads.listThread` when they are opened.
+- **Who is signed in is read when subscribing.** After someone signs in or out, subscribe again. Reloading the document with the SDK's `setDocument`, as the getting-started guide does when the user changes, does that.
+- **A listener that fails stops.** A visitor subscribing to a scope without `anonymousRead`, or rules that are not deployed, end the subscription; `onListenError` (default `console.error`) is told why.
+
+## Develop
+
+The rules and the adapter are tested against the Firestore and Auth emulators, with the shared contract suites and the access-rule tests in `test/`. The emulators need Java 21; `firebase-tools` comes from `pnpm dlx`, at the version pinned in the `test:emulator` script, and downloads the Firestore emulator on first use.
+
+```sh
+cd packages/adapter-firebase
+pnpm test:emulator   # starts the emulators from firebase.json, runs the tests, stops them
+```
+
+`scripts/ci-local.sh adapter-firebase` runs the same.

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import type { Auth } from "firebase/auth";
+import { type Firestore, type FirestoreError } from "firebase/firestore";
+import { type Annotation, type ChangeEvent, type ListQuery, type StorageAdapter, type ThreadStore, type Unsubscribe, type VersionStore } from "@acornly/core";
+export interface FirebaseAdapterOptions {
+    /** The site's own Firestore, with the shipped `firestore.rules` deployed to it. */
+    firestore: Firestore;
+    /**
+     * The site's Firebase Auth. The adapter reads and writes as whoever is signed in on it, or as a
+     * visitor when nobody is. Anonymous sign-ins count as visitors: they read, but cannot write.
+     */
+    auth: Auth;
+    /**
+     * Called when a subscription's snapshot listener fails, for example when a visitor who is not
+     * signed in subscribes to a scope without `anonymousRead`, or the rules are not deployed.
+     * Firestore stops a failed listener; subscribe again to retry. Defaults to `console.error`.
+     */
+    onListenError?: (error: FirestoreError) => void;
+}
+/**
+ * Keeps annotations in a site's own Firestore, checked by the security rules this package ships
+ * (`firestore.rules`). Each write is a Firestore transaction that reads what it depends on, so
+ * concurrent edits conflict instead of overwriting each other, and the rules check every write.
+ *
+ * Subscribers hear about this adapter's own writes at once, and about everyone else's through
+ * Firestore snapshot listeners, which the same rules filter.
+ */
+export declare class FirebaseAdapter implements StorageAdapter {
+    readonly capabilities: {
+        realtime: boolean;
+        search: boolean;
+        offline: boolean;
+    };
+    private readonly db;
+    private readonly auth;
+    private readonly notes;
+    private readonly listeners;
+    private readonly onListenError;
+    constructor(options: FirebaseAdapterOptions);
+    /** Earlier versions, in `acornly_versions`: only the note's author can save or read them. */
+    readonly versions: VersionStore;
+    /**
+     * Reply threads. Each write is one transaction, and the rules check each new child against
+     * its parent and keep every note's list of children in step, so a delete knows whether a note
+     * still has children, even ones the deleter cannot read.
+     */
+    readonly threads: ThreadStore;
+    /**
+     * Removes `start` in `tx`, then each placeholder above it left with no children, up to
+     * `CHAIN_STEP` notes, and takes the last one out of the children of the note above it. `next`
+     * is that note when it is a placeholder left with no children, still to remove.
+     */
+    private removeUp;
+    list(q: ListQuery): Promise<Annotation[]>;
+    get(id: string): Promise<Annotation | null>;
+    create(a: Annotation): Promise<Annotation>;
+    update(a: Annotation, expectedRev: number): Promise<Annotation>;
+    remove(id: string, expectedRev: number): Promise<void>;
+    subscribe(q: Omit<ListQuery, "since">, onChange: (e: ChangeEvent) => void): Unsubscribe;
+    /** Who is signed in: `member` when with an account, not an anonymous sign-in. */
+    private who;
+    /** The signed-in account a write is made as. */
+    private writer;
+    private noteRef;
+    private versionsRef;
+    /** The stored note, or null when it is missing or the caller cannot read it. */
+    private readDoc;
+    /**
+     * The notes matching `constraints` that the caller can read: the public ones, and their own.
+     * The rules refuse any query that could return a note the caller cannot read, so each query
+     * asks for one of those two kinds.
+     */
+    private readAll;
+    /**
+     * Runs a query. A visitor is refused a scope without `anonymousRead` as a whole query, which
+     * reads as finding nothing, as it would under row-level security.
+     */
+    private fetch;
+    private count;
+    /**
+     * Runs `body` in a Firestore transaction, which Firestore may retry when what it read changed
+     * meanwhile. The rules refusing a write becomes a plain "not allowed".
+     */
+    private transact;
+    /**
+     * Plain updates keep the tree: no note moves to another scope, document or thread, `deleted`
+     * changes only through `deleteNode`, a placeholder is never edited, a note with children keeps
+     * its author, and a child keeps its parent rev and gets no wider than its parent. The rules
+     * check the same, but cannot say which rule a write broke.
+     */
+    private checkTreeKept;
+    private onRemote;
+    /** Tells this adapter's subscribers about one of its own writes. */
+    private emit;
+    private tell;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAeL,KAAK,SAAS,EACd,KAAK,cAAc,EAIpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAYL,KAAK,UAAU,EACf,KAAK,WAAW,EAEhB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,sBAAsB;IACrC,mFAAmF;IACnF,SAAS,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,IAAI,CAAC;IACX;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CACjD;AA8ED;;;;;;;GAOG;AACH,qBAAa,eAAgB,YAAW,cAAc;IACpD,QAAQ,CAAC,YAAY;;;;MAAqD;IAC1E,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAO;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;gBAEpD,OAAO,EAAE,sBAAsB;IAO3C,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAyC7B;IAEF;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAsG3B;IAEF;;;;OAIG;YACW,QAAQ;IAiChB,IAAI,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAMzC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAK3C,MAAM,CAAC,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAyB1C,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAc/D,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB5D,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,WAAW;IAgEvF,iFAAiF;YACnE,GAAG;IAMjB,gDAAgD;YAClC,MAAM;IAMpB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,WAAW;IAInB,gFAAgF;YAClE,OAAO;IAWrB;;;;OAIG;YACW,OAAO;IAgBrB;;;OAGG;YACW,KAAK;YAUL,KAAK;IASnB;;;OAGG;YACW,QAAQ;IAStB;;;;;OAKG;YACW,aAAa;IAqC3B,OAAO,CAAC,QAAQ;IA2BhB,oEAAoE;IACpE,OAAO,CAAC,IAAI;IAoBZ,OAAO,CAAC,IAAI;CAUb"}