web-annotation-discovery-server

Web Annotation Discovery Server

This server enables people to store and publish annotations on the web, as described in the Web Annotation Discovery proposal.

It has been developed and tested in combination with the Web Annotation Discovery WebExtension browser extension. Other clients that speak the Web Annotation Protocol should be compatible too (if, for writing to the server, they support HTTP Basic Authentication).

Status

Minimum viable product, or primarily a proof-of-concept: This software demonstrates a mechanism for web annotation in practice, enabling people to try it out and hopefully move forward with the idea.

The software can be used for collaborative annotation, but be prepared for possible technical glitches (including data loss or leakage), mediocre user experience, and awful interface design.

Try it out

Install & run

Tested with NodeJS version 16 (LTS).

1. Clone this repository: git clone …

2. Install dependencies: npm install

3. Add a user (or several) in config/users.json

4. Run the server: npm start

Use

Point your browser to your server (by default it’s http://localhost:8080/), click your username and create a collection. Name it e.g. “My notes”. The browser should prompt you now for your username and password, which it remembers for subsequent requests. (Without any obvious way to log out, however..)

For the next steps, ensure you have the Web Annotation Discovery WebExtension installed and enabled in your browser.

Visit the collection’s URL, e.g. http://localhost:8080/alice/my_notes/. The browser extension will discover the <link> tag in the collection page, and offer to subscribe to this collection.

The browser extension will then display notes in the collection on pages you visit, and let you select this collection for any new annotations you make. See the documentation of the browser extension for more explanation on its usage.

Security & Access control

When publicly accesible, always run this server behind a reverse proxy that only permits connection via TLS. Authentication is performed using the HTTP Basic Authentication, so passwords would otherwise be sent around the world in plaintext.

The list of known users and their passwords is configured in config/users.json. The default is alice with password secret123.

By default, data is stored in /tmp/annotationdb; configure this in config/config.json.

Note that all annotations on the server are publicly readable. Only the owner of a collection can create/modify annotations in it. More granular control has not (yet) been implemented, but your reverse proxy could shield of a user’s whole path (i.e. /username/*) or individual collections (/username/collection_name/*) if desired.

Develop

Install dependencies using npm install; then running npm start should spin it up. Or npm run dev runs it with live reloading upon source file changes.

Code tour

This server is derived from simple-annotation-server by Jan Kaßel, converted from JavaScript and hapi to TypeScript and Express, among other changes; but still using the Level database. Besides the JSON interface for the Web Annotation Protocol, this version also renders users, collections and annotations as HTML.

For authentication (for POST/PUT/DELETE requests), HTTP Basic Authentication is used, as it is simple and (somewhat) supported by most web browsers.

Licence

Much of this code is derived from simple-annotation-server by Jan Kaßel, MIT-licensed.

Anything else in this repository is free and unencumbered software released into the public domain.

Acknowledgements

This project was funded through the NGI0 Discovery Fund, a fund established by NLnet with financial support from the European Commission’s Next Generation Internet programme.