Open source d16n documentation (#1)

Add initial README, LICENSE and specification document

.github/workflows/deploy-gh-pages.yaml

@@ -0,0 +1,43 @@
+name: "Build and Deploy to GitHub Pages"
+# Based on https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+      - name: Install dependencies
+        run: |
+          gem install -g dependencies/Gemfile
+      - run: |
+          mkdir _site
+          cp -r spec _site/spec
+          make -C _site/spec
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site/
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 bettermarks GmbH
+
+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.

README.md

@@ -1 +1,120 @@
-# D16N
+<p align="right">
+  <img src="images/eu_funded.png" alt="EU funded project" width="200" valign="top">
+</p>
+
+<p align="center">
+  <img src="images/logo-d16n.webp" alt="D16N - Depseudonymisation" width="400">
+</p>
+<p align="center">
+  <b>d16n - Depseudonymisation</b>
+</p>
+
+## Description
+
+![Connection: sequence SVG](diagrams/connection.svg)
+
+
+### Why
+
+<!--
+
+Here I think we want to write about how the GDPR or we in the EdTech industry
+place a particulary high value on the data privacy of children.
+Children are of particular importance - they have so much to learn!
+
+Why should EdTech's be interested in this specification?
+... something about the benefits of implementing specs
+... something about lower burden of GDPR compliance
+
+-->
+
+#### _Draft 1_
+
+Children have a lot to learn, so we want to offer them digital learning
+experiences in the form of apps.
+
+In order to have a productive learning experience,
+their teachers need to be able to identify the work of their students.
+This is easiest when the teacher can see their students identified by the same
+name they use in all apps and, in particular, the name used in the classroom.
+
+However, as app creators we have a special duty to protect the personal data
+of children. The simplest way to do that is to not receive it.
+
+#### _Draft 2_
+
+Per the [GDPR][GDPR],
+children merit specific protection with regard to their personal.
+The best way to protect that data is not to process it.
+
+We want to have a simple and common way for teachers to recognise their
+students without putting their data at risk.
+
+[GDPR]: https://eur-lex.europa.eu/eli/reg/2016/679/oj
+
+#### _Draft 3_
+
+As app creators we have a special duty to protect the personal data of
+children. The simplest way to do that is to not receive it.
+
+We want to have a simple and common way for teachers to recognise their
+students without putting their data at risk.
+
+### What
+
+This is a specification and implementation guide for interoperability of
+educational apps and user identity systems such that apps can show user
+names without revealing those names to the creator of the app.
+
+We name it client-side depseudonymisation or simply d16n.
+
+D16N refers to the Depseudonymisation process used in integrations, where
+pseudonyms (abstract IDs) are exchanged instead of clear user names. This
+functionality allows a user's browser to communicate directly with IDP
+servers to resolve these IDs into identifiable names. D16N enhances privacy by
+ensuring that user identities remain protected during data exchanges,
+particularly in educational contexts where sensitive information is involved.
+
+### For Whom
+
+- You are an Identity Provider who works in the education system.
+- You are an EdTech with an app to use in the school system.
+
+
+## Specification
+
+The latest version of the specification is 1.0
+
+The rendered version can be viewed [here](https://bettermarks.github.io/d16n/spec/d16n-v1_0.html).
+
+The source is found in [spec/](spec/)
+- [D16N Specification 1.0](spec/d16n-v1_0.adoc)
+
+
+## Implementers
+
+The following providers and apps have implemented this.
+Implementers can open a pull request against this repository to add their
+details.
+There is no certification process and implementations are not required to be
+open source.
+
+<!--
+TODO: ask bettermarks' existing partners if we/they can add their details here
+already.
+-->
+
+### Identity Providers
+
+Product Name        | Maintainers       | Point of Contact      | URL
+------------------- | ----------------- | --------------------- | -----------
+
+
+### Applications
+
+Product Name    | Maintainers      | Point of Contact           | URL
+--------------- | ---------------- | -------------------------- | --------------------------
+bettermarks     | bettermarks GmbH | [email protected]    | https://bettermarks.com/
+
+
+

dependencies/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gem 'asciidoctor'

dependencies/README

@@ -0,0 +1,3 @@
+Dependency files for build processes
+
+Used by workflows in .github/workflows

diagrams/connection.puml

@@ -0,0 +1,20 @@
+@startuml
+skinparam backgroundColor white
+
+rectangle IDP #FAC711
+
+rectangle RelyingParty as "Relying Party" #D9D9D9 {
+  rectangle Client #FAC711
+  rectangle Server #85BCF0
+}
+
+IDP <-[#85BCF0]down-> Server : Authorization
+IDP -[#FAC711]left-> Client : Clear Names
+Client <-[#85BCF0]right- Server : Access Token
+
+ legend
+ |<back:#85BCF0>   </back>| Depseudonymized Area |
+ |<back:#FAC711>   </back>| Pseudonymized Area |
+ endlegend
+
+@enduml

diagrams/convert.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# converts all puml files to svg
+
+BASEDIR=$(dirname "$0")
+rm $BASEDIR/*.svg
+for FILE in $BASEDIR/*.puml; do
+  echo Converting $FILE..
+  FILE_SVG=${FILE//puml/svg}
+  cat $FILE | docker run --rm -i think/plantuml -nometadata -svg > $FILE_SVG
+  docker run --rm -v $PWD:/diagrams productionwentdown/ubuntu-inkscape inkscape /diagrams/$FILE_SVG --export-area-page --without-gui &> /dev/null
+done
+echo Done

spec/.gitignore

@@ -0,0 +1 @@
+*.html

spec/Makefile

@@ -0,0 +1,21 @@
+
+TARGETS = d16n-v1_0.html latest.html
+
+.PHONY: all
+all: $(TARGETS)
+
+.PHONY: preview
+preview: d16n-v1_0.html
+	@# TODO: this should be xdg-open on linux
+	open $<
+
+d16n-v1_0.html: d16n-v1_0.adoc
+	asciidoctor $<
+
+latest.html: d16n-v1_0.html
+	cp $< $@
+
+
+.PHONY: clean
+clean:
+	$(RM) $(TARGETS)

spec/README.md

@@ -0,0 +1,14 @@
+## Tools
+
+### `asciidoctor`
+
+You may find it useful to [install][adoc-install] `asciidoctor` to build locally.
+
+[adoc-install]: https://docs.asciidoctor.org/asciidoctor/latest/install/
+
+Unless the world has changed, it's likely a case of
+- `brew install asciidoctor` on macOS
+- `sudo apt-get install asciidoctor` on Ubuntu or
+- `nix-shell -p asciidoctor` on NixOS
+
+There's probably also a preview extension for your editor.