{"id":19382728,"url":"https://github.com/authzed/zanzibar-annotated","last_synced_at":"2025-04-09T09:11:29.281Z","repository":{"id":65501129,"uuid":"543260883","full_name":"authzed/zanzibar-annotated","owner":"authzed","description":"Google's Zanzibar paper annotated for folks outside of Google","archived":false,"fork":false,"pushed_at":"2025-04-08T05:01:04.000Z","size":3978,"stargazers_count":74,"open_issues_count":10,"forks_count":1,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-08T06:21:34.548Z","etag":null,"topics":["access-control","database","distributed-systems","documentation","fine-grained-authorization","google","graph-database","latency","rebac","research-paper","scale","security","zanzibar"],"latest_commit_sha":null,"homepage":"https://zanzibar.tech","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/authzed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-29T18:13:38.000Z","updated_at":"2025-04-04T02:20:58.000Z","dependencies_parsed_at":"2023-02-14T11:45:25.846Z","dependency_job_id":"3d9e1330-118e-4ed8-8002-2983278e122c","html_url":"https://github.com/authzed/zanzibar-annotated","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/authzed%2Fzanzibar-annotated","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/authzed%2Fzanzibar-annotated/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/authzed%2Fzanzibar-annotated/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/authzed%2Fzanzibar-annotated/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/authzed","download_url":"https://codeload.github.com/authzed/zanzibar-annotated/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008630,"owners_count":21032556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-control","database","distributed-systems","documentation","fine-grained-authorization","google","graph-database","latency","rebac","research-paper","scale","security","zanzibar"],"created_at":"2024-11-10T09:22:59.111Z","updated_at":"2025-04-09T09:11:29.262Z","avatar_url":"https://github.com/authzed.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zanzibar Annotated\n\n[![Discord Server](https://img.shields.io/discord/844600078504951838?color=7289da\u0026logo=discord 'Discord Server')](https://authzed.com/discord)\n[![Twitter](https://img.shields.io/twitter/follow/authzed?color=%23179CF0\u0026logo=twitter\u0026style=flat-square\u0026label=@authzed '@authzed on Twitter')](https://twitter.com/authzed)\n\nZanzibar 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.\nIt includes annotations that provide commentary on notable portions of the paper.\n\nLooking for further discussion of the paper? Join our [Discord].\n\nLooking to contribute? See [CONTRIBUTING.md].\n\n[discord]: https://authzed.com/discord\n[contributing.md]: https://github.com/authzed/zanzibar-annotated/blob/main/CONTRIBUTING.md\n\n## Getting Started\n\nFirst, run the development server:\n\n```bash\nyarn install\nPREVIEW_ENDPOINT=http://localhost:3000 yarn run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) with your browser to see the paper.\n\n## Overview\n\nThe paper is presented by a reader app developed using the [NextJS] framework, [Tailwind CSS] for styling, and [MDX] for markdown integration in React.\nThe markdown support also includes math typesetting using [Katex] and GitHub flavored features with [remark-gfm].\n\n[nextjs]: https://nextjs.org/\n[tailwind css]: https://tailwindcss.com/\n[mdx]: https://mdxjs.com/\n[katex]: https://katex.org/\n[remark-gfm]: https://github.com/remarkjs/remark-gfm\n\n## Features\n\n### Paper Content and Layout\n\nPaper content is written in Markdown using [GitHub flavored syntax] and [Katex].\nThe paper viewer app provides additional components that are used to provide layout instructions to emulate the actual published paper.\nThis is in order to preserve the ability to refer to specific column and page numbers of the paper.\n\n[GitHub flavored syntax]: https://github.github.com/gfm/\n\n### Shareable Highlights\n\nA 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.\nThis functionality is based on the [deeplinks.js] library.\n\n[deeplinks.js]: https://github.com/WesleyAC/deeplinks\n\n### Annotations\n\nAnnotations to paper content can be shown along side the related part of the paper.\nAdditionally, specific parts of the paper can be visibily highlighted and associated with an annotation.\n\nThe paper layout component expects an annotations context.\nThe [default annotation provider] implementation uses YAML files to store all annotations and provides hooks for components to get annotations and annotation related state.\n\nA collection of annotations can be organized into sets.\nEach set can be toggled on and off and can contain additional metadata to be displayed along side the paper.\n\n[default annotation provider]: https://github.com/authzed/zanzibar-annotated/blob/main/components/annotation.tsx\n\n#### YAML format\n\nOne YAML file per annotation set.\n\nAnnotation YAML file format:\n```\nid: \u003cAn identifier unique across annotation sets\u003e\nlabel: The short, human readable version of the id\ntitle: The descriptive name for the set\nsubtitle: Additional description of the set\ncta: Short Markdown string for a call to action or link to additional info.\ndescription: Markdown string for additional information about the set.\nhighlightColor: A tailwind color class name used to color code the annotations and highlights for this set. See https://tailwindcss.com/docs/customizing-colors\n\n(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\".)\ngroups:\n  page-1-col-2:\n    across-applications:\n    ...\n  page-2-col-1:\n    ...\n```\n\nSee the [content] directory for example.\n\n[content]: https://github.com/authzed/zanzibar-annotated/tree/main/content\n\n#### Linking\n\nAn annotation set can be directly linked using a URL fragment in the format:\n\n`#annotations/\u003cannotation set id\u003e`\n\nAn individual annotation can be directly linked using:\n\n`#annotations/\u003cannotation set id\u003e/\u003cannotation entry id\u003e`\n\n### Open Graph Support\n\nChromium 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].\nThis provides a rich preview of the paper content when a shareable link is posted to another site.\n\nIn the dev environment, set the PREVIEW_ENDPOINT env variable to your local instance (usually localhost:3000).\n\n_Note: The paper viewer app relies on a serverless function to generated the previews. Currently, [Vercel] is the only tested hosting service._\n\n[Puppeteer]: https://pptr.dev/\n[JSDOM]: https://github.com/jsdom/jsdom\n[Vercel]: https://vercel.com/\n\n## Host Your Own Paper\n\nOther papers can be hosted using this reader app by providing the paper contents in MDX and [deploying on Vercel].\n\n[Contribute] and get in touch if you do!\n\n[deploying on Vercel]: https://vercel.com/docs/concepts/get-started/deploy\n[contribute]: https://github.com/authzed/zanzibar-annotated/blob/main/CONTRIBUTING.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauthzed%2Fzanzibar-annotated","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fauthzed%2Fzanzibar-annotated","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauthzed%2Fzanzibar-annotated/lists"}