# 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][]).

[Web Annotation Discovery]: https://code.treora.com/gerben/web-annotation-discovery
[Web Annotation Discovery WebExtension]: https://code.treora.com/gerben/web-annotation-discovery-webextension
[Web Annotation Protocol]: https://www.w3.org/TR/annotation-protocol/
[HTTP Basic Authentication]: https://datatracker.ietf.org/doc/html/rfc7617


## 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.

[NodeJS]: https://nodejs.org/
[Web Annotation Discovery WebExtension]: https://code.treora.com/gerben/web-annotation-discovery-webextension

### 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.

[simple-annotation-server]: https://github.com/jankaszel/simple-annotation-server
[hapi]: https://hapi.dev/
[TypeScript]: https://typescriptlang.org/
[Express]: https://expressjs.com/
[Level]: https://github.com/Level/level
[Web Annotation Protocol]: https://www.w3.org/TR/annotation-protocol/


## 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.

[simple-annotation-server]: https://github.com/jankaszel/simple-annotation-server


## Acknowledgements

This project was [funded](https://nlnet.nl/project/WebAnnotation/) through the NGI0 Discovery Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme.