feat: add reproducible walkthrough for ODRL access control#2
Merged
Conversation
A Jupyter-book walkthrough demonstrating the FAIR2Adapt access control framework end-to-end using a synthetic biodiversity dataset. Three notebooks cover: DID identity setup, provider-side encryption + policy publishing, and consumer-side key unwrapping + decryption. The framework is production-ready — the same code paths protect the Hamburg urban pluvial flood risk dataset. Only the data is synthetic for reproducibility. Includes: - Synthetic Mediterranean biodiversity observations (20 rows, clearly labelled as fabricated) - Pre-generated public keys and DID documents for example provider and consumer identities - Example ODRL policy (Public Benefit purpose, attribute to FAIR2Adapt) - Science Live platform screenshots (policy create, policy view, grant view) - Jupyter-book configuration for rendering as HTML documentation - Consumer DID document at docs/example-consumer/did.json for GitHub Pages deployment Published nanopublications referenced in the walkthrough: - ODRL Policy: https://w3id.org/np/RATzaPLmaUtrmZ6w9WILh8jxF3F-e23xPrFHJQFO3-U6Y - ODRL Grant: https://w3id.org/np/RARNOf26WWMYa0BkLWpMURNRqjwSVGXj-4A9r9iCBpruM Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New workflow runs on push/PR when walkthrough or framework code changes: 1. Syncs jupytext .py → .ipynb 2. Executes all 3 notebooks end-to-end (smoke test) 3. Builds the Jupyter-book 4. Uploads the built book as an artifact Also updates deploy-pages.yml to copy the example-consumer DID document to GitHub Pages so did:web resolution works for the walkthrough. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
jupytext --sync requires pairing metadata in the .py files to know which .ipynb to generate. --to notebook explicitly converts each .py to .ipynb without needing the pairing config. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The walkthrough notebooks need consistent provider + consumer private keys across all three notebooks. Instead of regenerating keys on the fly (which breaks the key-wrapping chain), read private keys from GitHub Secrets — matching the Hamburg production pattern. Notebook 00 now raises a clear error if the private key is missing, with instructions for first-time local setup. Uses printenv (not echo) to write secrets to files, and chmod 600 to restrict permissions. GitHub Actions automatically masks secret values in logs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The root .gitignore has *.pem which blocked the public keys from being committed. Force-add them — these are PUBLIC keys (safe to share) needed by the walkthrough notebooks to wrap dataset keys and verify DID documents. Private keys remain gitignored. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A Jupyter-book walkthrough demonstrating the FAIR2Adapt access control framework end-to-end using a synthetic biodiversity dataset. The framework is production-ready — the same code paths protect the Hamburg urban pluvial flood risk dataset. Only the data is synthetic for reproducibility.
What's in this PR
Three notebooks (jupytext
.pyformat,.ipynbregenerated on demand):00_setup_did.py— Generate a decentralised identity (DID), create a DID document, publish it via GitHub Pages01_provider.py— Encrypt the dataset, load the ODRL policy, evaluate a consumer's access request, wrap the dataset key for the consumer's DID02_consumer.py— Unwrap the dataset key, decrypt the dataset, verify integrity, verify the access grantSupporting files:
data/synthetic-biodiversity-observations.csv— 20 rows of fabricated Mediterranean biodiversity observations (clearly labelled as synthetic throughout)keys/— pre-generated public keys + DID documents for example provider and consumer identities (private keys gitignored)policies/example-policy.jsonld— ODRL Offer policy (Use + Reproduce for Public Benefit, prohibit Commercialise/Sell, attribute to FAIR2Adapt)images/— Science Live platform screenshots (ODRL policy create form, policy view, access grant view)docs/example-consumer/did.json— consumer DID document for GitHub Pages deploymentPublished nanopublications referenced in the walkthrough:
Security
keys/.gitignore)Test plan
python 00_setup_did.py && python 01_provider.py && python 02_consumer.py)jupyter-book build .produces clean HTMLdocs/example-consumer/did.jsonfor DID resolution🤖 Generated with Claude Code