Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/authzed/zanzibar-annotated
Google's Zanzibar paper annotated for folks outside of Google
https://github.com/authzed/zanzibar-annotated
access-control database distributed-systems documentation fine-grained-authorization google graph-database latency rebac research-paper scale security zanzibar
Last synced: 4 days ago
JSON representation
Google's Zanzibar paper annotated for folks outside of Google
- Host: GitHub
- URL: https://github.com/authzed/zanzibar-annotated
- Owner: authzed
- License: apache-2.0
- Created: 2022-09-29T18:13:38.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-24T16:32:44.000Z (21 days ago)
- Last Synced: 2024-10-24T23:15:55.722Z (21 days ago)
- Topics: access-control, database, distributed-systems, documentation, fine-grained-authorization, google, graph-database, latency, rebac, research-paper, scale, security, zanzibar
- Language: TypeScript
- Homepage: https://zanzibar.tech
- Size: 2.9 MB
- Stars: 72
- Watchers: 7
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Zanzibar Annotated
[](https://authzed.com/discord)
[](https://twitter.com/authzed)
Zanzibar Annotated is a hosted copy of the [paper presented at USENIX ATC 2019](https://www.usenix.org/conference/atc19/presentation/pang) describing the Zanzibar authorization system.
It includes annotations that provide commentary on notable portions of the paper.
Looking for further discussion of the paper? Join our [Discord].
Looking to contribute? See [CONTRIBUTING.md].
[discord]: https://authzed.com/discord
[contributing.md]: https://github.com/authzed/zanzibar-annotated/blob/main/CONTRIBUTING.md
## Getting Started
First, run the development server:
```bash
yarn install
PREVIEW_ENDPOINT=http://localhost:3000 yarn run dev
```
Open [http://localhost:3000](http://localhost:3000) with your browser to see the paper.
## Overview
The paper is presented by a reader app developed using the [NextJS] framework, [Tailwind CSS] for styling, and [MDX] for markdown integration in React.
The markdown support also includes math typesetting using [Katex] and GitHub flavored features with [remark-gfm].
[nextjs]: https://nextjs.org/
[tailwind css]: https://tailwindcss.com/
[mdx]: https://mdxjs.com/
[katex]: https://katex.org/
[remark-gfm]: https://github.com/remarkjs/remark-gfm
## Features
### Paper Content and Layout
Paper content is written in Markdown using [GitHub flavored syntax] and [Katex].
The paper viewer app provides additional components that are used to provide layout instructions to emulate the actual published paper.
This is in order to preserve the ability to refer to specific column and page numbers of the paper.
[GitHub flavored syntax]: https://github.github.com/gfm/
### Shareable Highlights
A shareable URL is created when paper contents are selected and a visitor to that URL will be navigated directly to that portion of the paper.
This functionality is based on the [deeplinks.js] library.
[deeplinks.js]: https://github.com/WesleyAC/deeplinks
### Annotations
Annotations to paper content can be shown along side the related part of the paper.
Additionally, specific parts of the paper can be visibily highlighted and associated with an annotation.
The paper layout component expects an annotations context.
The [default annotation provider] implementation uses YAML files to store all annotations and provides hooks for components to get annotations and annotation related state.
A collection of annotations can be organized into sets.
Each set can be toggled on and off and can contain additional metadata to be displayed along side the paper.
[default annotation provider]: https://github.com/authzed/zanzibar-annotated/blob/main/components/annotation.tsx
#### YAML format
One YAML file per annotation set.
Annotation YAML file format:
```
id:
label: The short, human readable version of the id
title: The descriptive name for the set
subtitle: Additional description of the set
cta: Short Markdown string for a call to action or link to additional info.
description: Markdown string for additional information about the set.
highlightColor: A tailwind color class name used to color code the annotations and highlights for this set. See https://tailwindcss.com/docs/customizing-colors
(Annotations are organized into groups. Each group has an id such as "page-1-col-2" and each annotation has an id such as "across-applications".)
groups:
page-1-col-2:
across-applications:
...
page-2-col-1:
...
```
See the [content] directory for example.
[content]: https://github.com/authzed/zanzibar-annotated/tree/main/content
#### Linking
An annotation set can be directly linked using a URL fragment in the format:
`#annotations/`
An individual annotation can be directly linked using:
`#annotations//`
### Open Graph Support
Chromium and [Puppeteer] are used to dynamically generate a screenshot preview for selections and preview text is dynamically generated using [NextJS] server side rendering and [JSDOM].
This provides a rich preview of the paper content when a shareable link is posted to another site.
In the dev environment, set the PREVIEW_ENDPOINT env variable to your local instance (usually localhost:3000).
_Note: The paper viewer app relies on a serverless function to generated the previews. Currently, [Vercel] is the only tested hosting service._
[Puppeteer]: https://pptr.dev/
[JSDOM]: https://github.com/jsdom/jsdom
[Vercel]: https://vercel.com/
## Host Your Own Paper
Other papers can be hosted using this reader app by providing the paper contents in MDX and [deploying on Vercel].
[Contribute] and get in touch if you do!
[deploying on Vercel]: https://vercel.com/docs/concepts/get-started/deploy
[contribute]: https://github.com/authzed/zanzibar-annotated/blob/main/CONTRIBUTING.md