From e1b50794db7ddcf4b6adb4da67a5d4e5a1ce3c48 Mon Sep 17 00:00:00 2001 From: Stephen Curran Date: Fri, 20 Dec 2024 15:25:55 -0800 Subject: [PATCH] Initial version of the specification Signed-off-by: Stephen Curran --- .github/workflows/render-specs.yml | 9 +- .gitignore | 2 + README.md | 152 +++++ index.html | 878 +++++++---------------------- index.js | 366 ------------ multi-file-test/abstract.md | 3 - multi-file-test/features.md | 132 ----- multi-file-test/getting-started.md | 21 - multi-file-test/header.md | 17 - multi-file-test/index.html | 289 ---------- package-lock.json | 78 +-- package.json | 64 +-- readme.md | 150 ----- single-file-test/assets/test.json | 5 - single-file-test/assets/test.text | 1 - single-file-test/spec.md | 536 ------------------ spec/abstract.md | 3 + spec/definitions.md | 14 + spec/header.md | 19 + spec/references.md | 6 + spec/security_and_privacy.md | 0 spec/specification.md | 166 ++++++ spec/version.md | 0 specs.json | 81 +-- specup_logo.png | Bin 3194 -> 0 bytes 25 files changed, 669 insertions(+), 2323 deletions(-) create mode 100644 README.md delete mode 100644 index.js delete mode 100644 multi-file-test/abstract.md delete mode 100644 multi-file-test/features.md delete mode 100644 multi-file-test/getting-started.md delete mode 100644 multi-file-test/header.md delete mode 100644 multi-file-test/index.html delete mode 100644 readme.md delete mode 100644 single-file-test/assets/test.json delete mode 100644 single-file-test/assets/test.text delete mode 100644 single-file-test/spec.md create mode 100644 spec/abstract.md create mode 100644 spec/definitions.md create mode 100644 spec/header.md create mode 100644 spec/references.md create mode 100644 spec/security_and_privacy.md create mode 100644 spec/specification.md create mode 100644 spec/version.md delete mode 100644 specup_logo.png diff --git a/.github/workflows/render-specs.yml b/.github/workflows/render-specs.yml index 938d5d0..afb7c3e 100644 --- a/.github/workflows/render-specs.yml +++ b/.github/workflows/render-specs.yml @@ -4,7 +4,7 @@ name: spec-up-render on: push: branches: - - master + - main jobs: build-and-deploy-spec: @@ -13,18 +13,19 @@ jobs: contents: write steps: - name: Checkout 🛎️ - uses: actions/checkout@v2 # If you're using actions/checkout@v2 you must set persist-credentials to false in most cases for the deployment to work correctly. + uses: actions/checkout@v4 # If you're using actions/checkout@v4 you must set persist-credentials to false in most cases for the deployment to work correctly. with: persist-credentials: false - name: Install and Build 🔧 # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built. run: | npm install - node -e "require('./index')({ nowatch: true })" + node -e "require('spec-up')({ nowatch: true })" + rm -rf .gitignore rm -rf node_modules - name: Deploy - uses: peaceiris/actions-gh-pages@v3.7.3 + uses: peaceiris/actions-gh-pages@v4.0.0 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./ diff --git a/.gitignore b/.gitignore index 3546bd5..7053e8f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ +package-lock.json +index.html fonts # Logs diff --git a/README.md b/README.md new file mode 100644 index 0000000..5757de6 --- /dev/null +++ b/README.md @@ -0,0 +1,152 @@ +# The `did:webvh` DID Method -- `did:web` + Verifiable History + +The spec repository for the `did:webvh` DID Method. `did:webvh` is `did:web` +extended to include the Verifiable History of the DID. + +Read the spec: [https://identity.foundation/didwebvh](https://identity.foundation/didwebvh/next) + +Proof of concept implementations available: + +- Typescript: [https://github.com/decentralized-identity/trustdidweb-ts](https://github.com/decentralized-identity/trustdidweb-ts) +- Python: [https://github.com/decentralized-identity/trustdidweb-py](https://github.com/decentralized-identity/trustdidweb-py) +- Go: [https://github.com/nuts-foundation/trustdidweb-go](https://github.com/nuts-foundation/trustdidweb-go) +- Python Web Server: [https://github.com/decentralized-identity/trustdidweb-server-py](https://github.com/decentralized-identity/trustdidweb-server-py) + +## Current Status of the Specification + +The current stable version of the specification can be found at +[https://identity.foundation/didwebvh](https://identity.foundation/didwebvh). +See any guidance there about the status of the specification -- past versions, +upcoming changes, etc. + +## Abstract + +The `did:webvh` DID Method is an enhancement to the well-known `did:web` DID +method, providing a complementary web-based DID method that addresses +limitations of `did:web`, most notability, the verifiable history for which it +is name. `did:webvh` features include the following. + +- Ongoing publishing of all DID Document (DIDDoc) versions for a DID instead of, + or alongside a `did:web` DID/DIDDoc. +- Uses the same DID-to-HTTPS transformation as `did:web`. +- Provides resolvers the full history of the DID using a verifiable chain of + updates to the DIDDoc from genesis to deactivation. +- A self-certifying identifier (SCID) for the DID that is globally + unique and derived from the initial DIDDoc that enables DID portability, such + as moving the DIDs web location (and so the DID string itself) while retaining + the DID's history. +- DIDDoc updates include a proof signed by the DID Controller(s) *authorized* to + update the DID. +- An optional mechanism for publishing "pre-rotation" keys to prevent loss of + control of the DID in cases where an active private key is compromised. +- An optional mechanism for having collaborating "witnesses" + that approve updates to the DID by the DID Controller before publication. +- DID URL path handling that defaults (but can be overridden) to automatically + resolving `/path/to/file` by using a comparable DID-to-HTTPS translation + as for the DIDDoc. +- A DID URL path `/whois` that defaults to automatically returning (if + published by the DID controller) a Verifiable Presentation containing + Verifiable Credentials with the DID as the `credentialSubject`, + signed by the DID. + +Combined, the additional features enable greater trust, security and +verifiability without compromising the simplicity of `did:web`. The incorporation +of the DID Core compatible "/whois" path, drawing inspiration from the +traditional WHOIS protocol, offers an easy to use, decentralized, trust +registry. `did:webvh` aims to establish a more trusted and secure web +environment by providing robust verification processes and enabling transparency +and authenticity in the management of decentralized digital identities. + +## Contributing to the Specification + +Pull requests (PRs) to this repository may be accepted. Each commit of a PR must +have a DCO (Developer Certificate of Origin - +[https://github.com/apps/dco](https://github.com/apps/dco)) sign-off. This can +be done from the command line by adding the `-s` (lower case) option on the `git +commit` command (e.g., `git commit -s -m "Comment about the commit"`). + +Rendering and reviewing the spec locally for testing requires `npm` and `node` +installed. Follow these steps: + +- Fork and locally clone the repository. +- Install `node` and `npm`. +- Run `npm install` from the root of your local repository. +- Edit the spec documents (in the `/spec` folder). +- Run `npm run render`' + - Use `npm run edit` to interactively edit, render and review the spec. +- Review the resulting `index.html` file in a browser. + +The specification is currently in [Spec-Up] format. See the +[Spec-Up Documentation] for a list of Spec-Up features and functionality. + +[Spec-Up]: https://github.com/decentralized-identity/spec-up +[Spec-Up Documentation]: https://identity.foundation/spec-up/ + +## Publishing Previous Spec Versions + +[Spec-Up] allows for multiple versions of the spec to be rendered and accessed +on the same site. We use that feature for the `did:webvh` DID Method spec to snapshot +previous versions of the spec for reference. + +To create a snapshot of a version: + +- Make a new folder in the root of the repository for the new version, called `spec-v`. For example `v0.3`. +- Copy the `spec` folder markdown files from the point of that version into the new folder. If you are doing this process as you are starting a new version, you can just copy the files from the `spec` folder of the main branch. Otherwise, you have to find the last commit of the version and get the files from that point in the GitHub history. +- Update the `specs.json` file to include a new specification: + - Copy the primary spec entry text. + - Paste that text into a new spec entry in the `"specs"` array. + - Update the `"spec_directory"` property to be the name of the new folder you created. + - Update the `"output_path"` property to be `./v`. For example `"./v0.3"`. + - Append to the `"title"` property the version ` - Version `, For example ` - Version 0.3`. +- Add a link to the versioned specification in the `Previous Drafts` bullet list, in the `header.md` file in the main spec, so that readers can click on it from the main specification. +- Update the `header.md` file of the new version spec folder (e.g in `spec-v0.3`) to: + - Change the status to `HISTORICAL -- **THIS IS NOT THE CURRENT VERSION OF THE SPECIFICATION**` + - As appropriate, add guidance for readers **WITHOUT** altering the version of the specification itself. + - Remove the `Past Drafts` section and put a relative link back to the current spec -- such as: + +```text +**Latest Version:** + +- Specification: [https://identity.foundation/didwebvh/](../) +- Repository: [https://github.com/decentralized-identity/didwebvh](https://github.com/decentralized-identity/didwebvh) + +``` + +## Handling Version Transitions + +In the lifecycle of the specification, there will be times when the latest version is +stable, with clarifications being added, and other times when new versions are being defined +with breaking changes. We use the Spec-Up multiple versions feature +(as described above) to support that, but it can get a little tricky. Notably, we want +the landing page for the specification to **always** be the current version of +the specification, **and** we want all "in progress" work to be to made to the +single, primary specification -- the files in the `spec` folder -- so that GitHub +holds the full history of the specification. To enable that, we adjust as +needed the `"output_path"` in the `specs.json` file to define what version of +the spec is on the specification landing page -- the spec version whose +`"output_path"` is set to `"./"`). + +Here's how we do that in different situations: + +- When the specification is stable, the `spec` folder is the landing page, and + past versions are linked in that folder's `header.md` file as "past versions". +- When a new version of the specification with breaking changes is ready to be worked on: + - Snapshot the stable specification version by creating a new directory (e.g., + `spec-v0.4`) and copying the files from the `spec` folder into the new + folder. + - Create a new entry in the `specs.json` file for that new snapshot version. + - Set the `output_path` of the new version (e.g., `spec-v0.4`) to be `"./"`, + so that it becomes the landing page. + - Change the `output_path` of the primary `spec` folder entry to `"./next"`. + - Update the `header.json` files in both the new folder and the `spec` folder + to link to one another, adding any notes to help readers understand the + status of the current and next versions of the specification. +- When the "next" version of the specification stabilizes, revert to the + "normal" state of the `spec` folder being the landing page. + - Change the `output_path` of the primary `spec` folder to `"./"`. + - Change the `output_path` of the formerly "current" spec version to a path + that includes its version (e.g., `"./v0.4"`). + - Update the `header.json` files in both the (now past version) folder and the + `spec` folder to link to one another's new `output_path` values, remove any + clarification notes that no longer apply, and make the past version "just + another" past version (e.g., like `spec-v0.3`) diff --git a/index.html b/index.html index aa254de..68a5fbc 100644 --- a/index.html +++ b/index.html @@ -6,7 +6,7 @@ - Spec-Up Example + DID /whois @@ -15,10 +15,10 @@ code[class*=language-],pre[class*=language-]{color:#ccc;background:0 0;font-family:Consolas,Monaco,'Andale Mono','Ubuntu Mono',monospace;font-size:1em;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;word-wrap:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none}pre[class*=language-]{padding:1em;margin:.5em 0;overflow:auto}:not(pre)>code[class*=language-],pre[class*=language-]{background:#2d2d2d}:not(pre)>code[class*=language-]{padding:.1em;border-radius:.3em;white-space:normal}.token.block-comment,.token.cdata,.token.comment,.token.doctype,.token.prolog{color:#999}.token.punctuation{color:#ccc}.token.attr-name,.token.deleted,.token.namespace,.token.tag{color:#e2777a}.token.function-name{color:#6196cc}.token.boolean,.token.function,.token.number{color:#f08d49}.token.class-name,.token.constant,.token.property,.token.symbol{color:#f8c555}.token.atrule,.token.builtin,.token.important,.token.keyword,.token.selector{color:#cc99cd}.token.attr-value,.token.char,.token.regex,.token.string,.token.variable{color:#7ec699}.token.entity,.token.operator,.token.url{color:#67cdcc}.token.bold,.token.important{font-weight:700}.token.italic{font-style:italic}.token.entity{cursor:help}.token.inserted{color:green}pre[class*=language-].line-numbers{position:relative;padding-left:3.8em;counter-reset:linenumber}pre[class*=language-].line-numbers>code{position:relative;white-space:inherit}.line-numbers .line-numbers-rows{position:absolute;pointer-events:none;top:0;font-size:100%;left:-3.8em;width:3em;letter-spacing:-1px;border-right:1px solid #999;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.line-numbers-rows>span{display:block;counter-increment:linenumber}.line-numbers-rows>span:before{content:counter(linenumber);color:#999;display:block;padding-right:.8em;text-align:right} @keyframes chartjs-render-animation{from{opacity:.99}to{opacity:1}}.chartjs-render-monitor{animation:chartjs-render-animation 1ms}.chartjs-size-monitor,.chartjs-size-monitor-expand,.chartjs-size-monitor-shrink{position:absolute;direction:ltr;left:0;top:0;right:0;bottom:0;overflow:hidden;pointer-events:none;visibility:hidden;z-index:-1}.chartjs-size-monitor-expand>div{position:absolute;width:1000000px;height:1000000px;left:0;top:0}.chartjs-size-monitor-shrink>div{position:absolute;width:200%;height:200%;left:0;top:0} :root{--base-theme-color:207,71%;--themed-element-bk:hsl(var(--base-theme-color), 40%);--themed-element-text:#fff;--themed-element-border:1px solid hsl(var(--base-theme-color), 26%);--themed-heading-text:hsl(var(--base-theme-color), 30%);--no-color:255,255,255;--faint-color:245,245,245;--dim-color:225,225,225;--low-color:200,200,200;--mid-color:100,100,100;--high-color:50,50,50;--full-color:0,0,0;--active-color:#3aaaff;--visited-color:rgb(188, 129, 255);--green-status:rgb(0, 123, 9);--light-green-status:rgb(0, 194, 13);--page-bk:rgb(var(--no-color));--page-text:rgb(var(--full-color));--page-text-hover:rgb(var(--full-color));--element-bk:rgb(var(--no-color));--element-bk-hover:rgba(var(--low-color), 0.5);--element-bk-transparent:rgba(var(--dim-color), 0.92);--element-border:rgba(var(--high-color), 0.4);--element-border-focus:rgb(var(--full-color), 0.75);--element-border-radius:3px;--element-shadow-low:0 1px 3px 0px rgba(0,0,0, 0.25);--element-shadow-mid:0 1px 3px 0px rgba(0,0,0, 0.35);--element-shadow-high:0 1px 5px 0px rgba(0,0,0, 0.45);--code-bk:#1a1e23;--input-bk:rgba(var(--dim-color), 0.6);--input-border:rgba(var(--high-color), 0.4);--header-height:48px;--header-bk:rgba(var(--low-color), 0.985);--header-text:rgb(var(--full-color));--header-border:rgba(var(--full-color), 0.1);--header-border-inverse:rgba(var(--no-color), 0.3);--text-shadow:0 1px 2px rgba(0,0,0,0.8);--svg-size:2vw;--font-size:14px}:target{scroll-margin:calc(var(--header-height)/ .75) 0 0}body:not([hashscroll]) :target{animation:highlight 1.5s .25s ease}body{margin:0;padding:0;font-family:Heebo,san-serif;line-height:1.5em;widows:2;orphans:2;word-wrap:break-word;overflow-wrap:break-word;color:#000;word-spacing:1px;counter-reset:h2 toc1}h1{font-size:2em;font-weight:700;line-height:1.2em}h2{margin:1.5em 0 1em}blockquote{position:relative;padding:0;margin:1.75em .75em;color:rgb(var(--mid-color));background:rgb(var(--faint-color))}blockquote:after,blockquote:before{content:"“";position:absolute;top:.065em;left:.065em;font-size:3em;height:.34em;line-height:100%;color:rgb(var(--low-color))}blockquote:after{content:"”";top:auto;left:auto;bottom:.065em;right:.065em;text-align:center}blockquote>p{padding:.6em 1.8em .5em 1.8em}strong strong{font-size:.9em;color:#b30032;font-weight:400;text-transform:uppercase}main article>ol,main article>ul{padding:0 0 0 2em}main article h1,main article h2,main article h3,main article h4,main article h5,main article h6{color:var(--themed-heading-text)}main article h2,main article h3,main article h4{display:flex;font-weight:500}main article h2{counter-reset:h3 h4}main article h3{counter-reset:h4}main article h2:after{counter-increment:h2;content:counter(h2) ".";padding:0 .4em 0 .2em;order:-1}main article h3:after{counter-increment:h3;content:counter(h2) "." counter(h3);padding:0 .45em 0 .2em;order:-1}main article h4:after{counter-increment:h4;content:counter(h2) "." counter(h3) "." counter(h4);padding:0 .5em 0 .2em;order:-1}h1 .toc-anchor{display:none}.toc-anchor{margin:-.1em 0 0;font-size:.875em;color:inherit;text-decoration:none;opacity:.35;order:-1;transition:opacity .3s ease}.toc-anchor:hover{opacity:1}pre{overflow:auto}code{padding:.085em .3em .1em;font-size:1.075em;color:#c7001c;vertical-align:middle;background:#f0f0f0;border-radius:4px}pre code{background:unset;padding:unset;border-radius:unset}h1 code,h2 code,h3 code,h4 code,h5 code,h6 code{font-size:1.25em;margin:-.11em .3em 0 0;border-radius:3px}ol,ul{margin:0;padding:0 0 0 1.2em}dt{font-weight:700;margin:1em 0 0}dd{margin-left:1.5em}main{box-sizing:border-box;float:right;width:75%;min-width:calc(100% - 325px);max-width:calc(100% - 275px);padding:.5em 2em 1.5em 2em;background:#fff;box-shadow:0 0 5px -1px rgba(0,0,0,.3)}main table{display:block;width:-webkit-fill-available;width:fit-content;max-width:100%;margin:1.5em 0 1.75em;border-spacing:0;border-collapse:collapse;overflow-x:auto;word-wrap:normal;overflow-wrap:normal;hyphens:manual}main thead tr th{color:var(--themed-element-text);background:var(--themed-element-bk);border:var(--themed-element-border);text-shadow:0 1px 1px rgba(0,0,0,.5)}main tr{border-top:1px solid #ccc;background-color:#fff;margin:0;padding:0}main tr:nth-child(2n){background-color:#f0f0f0}main tr th{font-weight:400;border:1px solid #ccc;text-align:left;margin:0;padding:6px 13px}main td,main th{padding:9px 13px;border:1px solid #d8d8d8}main tr td{border:1px solid #ccc;text-align:left;margin:0;padding:.55em .75em .55em}main tr td :first-child,main tr th :first-child{margin-top:0}main tr td :last-child,main tr th :last-child{margin-bottom:0}table pre[class*=language-]{border:none;border-radius:0}table pre[class*=language-]:before{display:none}svg[icon]{width:1.25em;height:1.25em;vertical-align:text-top;pointer-events:none}article p>img{max-width:100%;margin:0 auto}article li{margin-top:.4em}slide-panel>:not(header):not(footer){flex:1}:not(pre)>code[class*=language-],pre[class*=language-]{padding:.65em .8em .8em;background:var(--code-bk)}.tippy-box{box-shadow:var(--element-shadow-mid)}.tippy-box a{color:var(--active-color)}.tippy-box a:visited{color:var(--visited-color)}.tippy-content{padding:.55em .55em .5em}.tippy-content header{margin:0 0 .4em;padding:.15em .3em .1em;border-radius:2px;background:rgba(255,255,255,.1);text-shadow:0 1px rgba(0,0,0,.9)}.tippy-content table,.tippy-content tbody,.tippy-content td,.tippy-content tr{margin:0;padding:0;border:none;border-spacing:0;border-collapse:collapse;background:0 0!important;background-color:transparent!important}.tippy-content table{margin:0 .3em}.tippy-content td{font-size:.9em;padding:.2em 0 0}.tippy-content td:first-child{padding-right:.5em}a[path-0$="github.com"]:before{content:"\f09b";color:var(--page-text);margin:0 .25em 0 0;font-family:FontAwesome;text-decoration:none;display:inline-block;vertical-align:bottom}a[path-0$="github.com"][path-3=issues][path-4],a[path-0$="github.com"][path-3=projects],a[path-0$="github.com"][path-3=pull],a[path-0$="github.com"][path-3=releases]{text-decoration:none}a[path-0$="github.com"][path-3=issues][path-4] span,a[path-0$="github.com"][path-3=projects] span,a[path-0$="github.com"][path-3=pull] span,a[path-0$="github.com"][path-3=releases] span{display:none}a[path-0$="github.com"][path-3=issues][path-4]:after{content:"Issue #" attr(path-4)}a[path-0$="github.com"][path-3=pull]:after{content:"Pull Request #" attr(path-4)}a[path-0$="github.com"][path-3=releases][path-5]:after{content:"Release " attr(path-5)}a[path-0$="github.com"][path-3=projects]:after{content:"Project #" attr(path-4)}[issue-count]:after{content:"Issues (" attr(issue-count) ")";margin:0 0 0 .3em;padding:.1em 0 0}[issue-count=""][animate]{display:none;opacity:0}[issue-count][animate]:not([issue-count=""]){animation:display-show 1s}[panel-toggle]{cursor:pointer}.panel-header{display:flex;align-items:center;height:var(--header-height)}.panel-header>*{display:flex;height:100%;padding:.1em .8em 0;align-items:center}.slide-panel{width:calc(100% - 1em);max-width:475px;transition:transform .35s ease}.slide-panel[panel-open]{transform:translateX(0)}.notice{margin:1em 0;padding:.5em .9em .55em .65em;border-left:.5em solid}.notice p{margin:.4em 0 0}.note{background:#e9fbe9;border-color:#52e052}.note .notice-link{display:block;color:#178217}.issue{background:#e9f0fb;border-color:#527fe0}.issue .notice-link:before{display:block;color:#1e4cae}.warning{background:#fbe9e9;border-color:#e05252}.warning .notice-link{display:block;color:#ae1e1e}.example{color:#cebe00;background:#1a1e23;border-left:.5em solid}.example .notice-link{display:block;color:inherit;font-size:1.1em;font-family:Heebo,san-serif}.example pre[class*=language-]{padding:0;border-radius:0}.todo{background:#fbe4ff;border-color:#9700e2}.todo .notice-link{display:block;color:#6d00a2}.mermaid{display:flex;align-items:center;justify-content:center;margin:1.5em 0 1.75em}.reference-list{margin:0;padding:0;list-style:none}.reference-list dd a,.reference-status{font-style:italic}.reference-status{color:var(--green-status)}.tippy-box .reference-status{color:var(--light-green-status)}code[class*=language-],pre,pre[class*=language-]{font-size:.9em;margin:1em 0 1.5em;border-radius:3px}.example code[class*=language-],.example pre,.example pre[class*=language-]{margin:0}#svg{display:none}#header{position:sticky;position:-webkit-sticky;padding:0;top:0;margin:-.5em -2em 0 -2em;background:rgba(255,255,255,.9);border-bottom:1px solid rgba(0,0,0,.175);box-shadow:0 1px 3px 1px rgba(0,0,0,.1);z-index:2}#logo{box-sizing:border-box;display:flex;align-items:center;height:100%;padding:.5em}#logo img{height:100%}#logo+span{margin-left:auto}#header #toc_toggle{display:none;padding:0 1em;border-right:1px solid rgba(0,0,0,.15)}#content{max-width:800px}#content h1:first-of-type{margin:1em 0 .5em}#content h1:first-of-type .markdownIt-Anchor{display:none}#repo_issues{width:calc(100% - 1.5em);max-width:450px;border-left:1px solid rgba(0,0,0,.15)}#repo_issues>header{background:#eee;border-bottom:1px solid #ddd}#repo_issues>header span:first-of-type{font-weight:700;padding-top:.1em}#repo_issues>header .repo-issue-toggle{margin-left:auto;color:inherit;font-weight:700;text-decoration:none}#repo_issue_list{list-style:none;margin:0;padding:0 1.25em 1.25em;font-size:.85em;overflow:auto;-ms-overflow-style:none;scrollbar-width:none}#repo_issue_list::-webkit-scrollbar{display:none}#repo_issue_list:empty:before{content:"No issues found";display:block;text-align:center;font-size:1.1em;color:#aaa;margin:1em 0 0}.repo-issue detail-box{display:flex;flex-direction:column;padding:1em 0;border-bottom:1px solid #ddd}.repo-issue detail-box>section{order:1}.repo-issue detail-box>section:empty+.repo-issue-title [detail-box-toggle]{display:none}.repo-issue-title{display:flex;align-items:center}.repo-issue-link{flex:1;margin:0 0 0 .5em}.repo-issue-number{height:1em;margin:0 .4em 0 0;padding:.3em .25em 0;border-radius:3px;font-weight:700;background:#eee;border:1px solid #ddd;text-align:center;line-height:1em}.repo-issue-number:before{content:"#";font-weight:400;margin:0 .1em 0 0}.repo-issue [detail-box-toggle]{margin:0 0 0 1em;opacity:.35;transition:opacity .4s}.repo-issue [detail-box-toggle]:hover,.repo-issue detail-box[open] [detail-box-toggle]{opacity:1}#toc{display:flex;flex-direction:column;width:25%;max-width:325px;min-width:275px;background:#eceff1}#toc header{color:var(--themed-element-text);background:var(--themed-element-bk);box-shadow:0 1px 3px 0 rgba(0,0,0,.3);border:var(--themed-element-border);border-top:none;border-left:none}#toc header [panel-toggle]{display:none;height:var(--header-height);line-height:var(--header-height);margin-left:auto;padding:0 1em;color:inherit;font-weight:700;text-decoration:none}#toc_list{flex:1;padding:1em .8em;overflow:auto}.toc{padding:0 0 1.75em;font-size:.85em}.toc,.toc ul{margin:0;list-style:none}.toc ul{padding:0 0 0 1em}.toc a{display:block;padding:.4em .3em .225em;text-decoration:none;border-radius:3px;color:#333}.toc a:before{color:#000;font-weight:700}.toc a:hover{text-shadow:0 1px 1px #fff;background:rgba(0,0,0,.1)}.toc>li a:before{counter-increment:toc1;content:counter(toc1) ".";padding:0 .4em 0 .2em}.toc>li>ul{counter-reset:toc2}.toc>li>ul>li a:before{counter-increment:toc2;content:counter(toc1) "." counter(toc2);padding:0 .45em 0 .2em}.toc>li>ul ul{counter-reset:toc3}.toc>li>ul ul li a:before{counter-increment:toc3;content:counter(toc1) "." counter(toc2) "." counter(toc3);padding:0 .5em 0 .2em}@media (min-width:900px){slide-panel{z-index:2}#slidepanels[open=sidebar]:before{opacity:0;transition:none;pointer-events:none}#slidepanels:before{z-index:1}#toc{transition:none;transform:translate3d(0,0,0);box-shadow:0 0 5px 1px rgba(0,0,0,.15) inset;z-index:0}}@media (max-width:900px){main{width:100%;min-width:auto;max-width:none;padding:.5em 1.25em 1.5em 1.25em}#header{margin:-.5em -1.25em 0 -1.25em}#toc header [panel-toggle]{display:block}#header #toc_toggle{display:flex}}@media (max-width:550px){td{font-size:.8em}}@keyframes display-show{0%{display:none;opacity:0}1%{display:block}100%{opacity:1}}@keyframes highlight{50%{background-color:#ff0}} - + - + @@ -38,8 +38,8 @@ - @@ -47,611 +47,230 @@
-

§ Spec-Up Example

+

§ DID /whois

Specification Status: Draft

Latest Draft: -https://identity.foundation/spec-up

+https://github.com/decentralized-identity/did-whois

-
Editors:
-
Daniel Buchner
-
Participate:
-
GitHub repo
-
File a bug
-
Commit history
+
Editors:
+
Stephen Curran
+
John Jordan
+
+ +
+
Participate:
+
GitHub repo
+
File a bug
+
Commit history

§ Abstract

-

Let’s face it, other tools and generators for writing technical specifications aimed at standards bodies or industry groups are cumbersome, underwhelming, and lack the features you might want in a technical specification document. Spec-Up’s goal is to deliver you a better spec-writing experience with far less effort and tedium than other tools in the ecosystem. Spec-Up is a simple tool that auto-generates great specs from markdown. The version of markdown Spec-up uses contains all the same features you might expect from common implementations, like GitHub, but adds much more, including notice blocks, complex tables, charts, advanced syntax highlighting, UML diagrams, etc.

-

§ Getting Started

-

Using Spec-Up is easy peasy lemon squeezy:

+

This document introduces a standardized <did>/whois DID URL path that provides a decentralized mechanism to retrieve a verifiable presentation published by the DID Controller, containing verifiable credentials about the DID and the entity controlling the DID.

+

§ DID Extension Specification: /whois

+

§ Introduction

+

The <did>/whois path introduces a convention for all DID Methods to enable a +resolver to learn more about the public identity of a DID Controller through the +discovery of Verifiable Credentials about the DID. Inspired by the WHOIS [RFC3912] +protocol from the early ARPANET days, this feature allows resolving +<did>/whois to retrieve a Verifiable Presentation (VP) containing Verifiable +Credentials containing public information about the DID Controller. This capability provides:

+
    +
  • A decentralized mechanism for querying verifiable information about DIDs.
    • +
  • A trust model based on cryptographic verification of attestations from +(possibly domain specific) authorities rather than centralized registries.
    • +
+

When <did>/whois is resolved using a DID service compliant with the [LINKED-VP], the response is a Verifiable Presentation (VP) +signed by the DID. The VP may contain:

+
    +
  • Information about the DID and the legal entity of the DID Controller that the +DID Controller wants to be made public.
    • +
  • Verifiable Credentials (VCs) with the DID as the credentialSubject that may +bind other identifiers (legal name, legal entity registration identifiers, +etc.) to the DID.
    • +
  • VCs with other identifiers bound (via other VCs in the VP) to the DID as the +credentialSubject.
    • +
+

For example, a VC in the VP may use the DID as the credentialSubject, +published by an authority, indicating the DID is associated with a legal entity +with a set of identifiers—such as the legal name of the entity and a +registration identifier (e.g., an LEI as published by GLEIF). A second VC in +the VP might use the entity identifier from that first VC as the +credentialSubject to include attestations such as ISO certifications. The +resolver decides whether to trust the issuers of the VCs, potentially using +/whois with those DIDs to gather information about their identity.

+

§ /whois Use Case

+

§ Example Scenario: Importing a Product Shipment

+

Consider the DID Controller of a mining company exporting a “product” +– a shipment of the material produced by their mine. The company publishes a +“Digital Product Passport” (DPP) in the form of a Verifiable Credential about +the shipment. An importer resolves the product identifier and retrieves and +verifies the DPP. It wants to know who it was that issued the (self-attested) +DPP verifiable credential. It finds in the DPP the DID of the issuer and then +resolves <did>/whois. The mining company has published a VP about its DID, +putting the following verifiable credentials containing public information into +the VP and signing it with its DID:

  1. -

    npm install spec-up

    +

    A Verifiable Credential attesting to the Legal Entity’s Registration:

    +
      +
    • Details such as the company’s legal name, registration date, and contact information might be included.
      • +
    • The credentialSubject of the VC is the same DID that signed the DPP, and the /whois VP.
      • +
    • This enables the importer to identify and verify the legitimacy of the company.
      • +
    • If necessary, the importer can resolve the <did>/whois of the issuer of the VC to learn more about them.
      • +
  2. -

    Create a specs.json file in the root folder of your repository to specify configuration values used in the generation of your spec documents. The values in your specs.json file include things like where your spec’s markdown files are located, where to output the generated spec document, and various metadata values used in rendering, such as the title, logo, and repo links for each of your specs. The following are the required/optional fields supported in the specs.json config file:

    +

    A Verifiable Credential for a Mining Permit:

      -
    • spec_directory (STRING, required) - You must specify the repo-root-relative location of your spec’s markdown file directory. You MUST name your spec’s markdown file spec.md and locate it in your spec_directory for the tool to automatically find and use it for rendering. If you want to use a different name for the markdown file, or you have multiple markdown files you would like the tool to assemble into one document, you must specify them using the optionalmarkdown_paths field described below. See the “multi-file” example in the spec-up repo.
      • -
    • title (STRING, required) - You must add a title for your spec, which will be rendered in the generated document’s H1 text and page title.
      • -
    • markdown_paths (ARRAY, optional) - If you want to name your spec’s markdown file something other than spec.md, or you have multiple files you would like assembled into a single output document, you must specify their paths as array entries in the order you would like them assembled. The paths in this array are assumed to be based on the spec_directory you specified, so DO NOT repeat the full root relative path.
      • -
    • katex (BOOLEAN, optional) - To enable TeX support via KaTeX, set this property to true. After rendering, be sure to copy the fonts/ subdirectory, containing the necessary web fonts.
      • -
    • output_path (STRING, optional) - If you want the generated spec document to be output to a different location than the spec_directory you specified (e.g. the project root for GitHub Pages publishing) you can specify another root relative path (use ./ for root), and the tool will write the document file there instead.
      • +
    • Issued by the mining authority (likely a government) in the company’s jurisdiction.
      • +
    • This second VC might use the company’s legal name as the +credentialSubject rather than the entity’s DID. The data in the first VC +provides the binding from the legal name to the DID.
      • +
    • Allows further resolution of the mining permit VC’s DID and its /whois +path for additional validation.
  3. -

    In your main node.js file, drop in this bad boy: require('spec-up')()

    +

    A Verifiable Credential for Auditing Practices:

    +
      +
    • Details about the company’s compliance with standards audited by a trusted entity.
      • +
    • Further resolution of the auditor’s DID /whois path may verify its accreditation.
      • +
-

Boom! That’s it. Spec-Up will auto-detect modifications to files in your spec_directory and auto-generate your spec’s updated HTML document every time you save a change.

-

Usage

-

If your spec.json and package.json and package-lock.json files are in working order and in the root folder of the repo from which it will be deployed, Spec-up can be called by command line (from the root of your repo) in three different modes:

- - - - - - - - - - - - - - - - - - - - - -
commandbehavior
npm run editafter rendering, this will stay running and the gulp library will watch the source files in your spec directory/ies for changes and re-render any time you save a file. Opening these rendered files in a browser and refreshing them will keep you up to date.
npm run renderthis renders the site once and does not keep a gulpy watch on the underlying files.
npm run devthis enables debugging features.
-

§ Table of Contents

-

<-- You see that beautiful TOC over there to your left? (tap the header link to slide it out on mobile) Yeah, you don’t need to do a damn thing, that just magically appears based on your use of h2, h3, and h4 headings.

-

§ Term References

-

§ Definition Lists

-

Many specs may want to include a section for terminology references, and Definition Lists are a great way to do that. Here’s how to leverage Spec-Up’s automatic term reference features via Definition List markup:

-
-[[def: Term 1, Term One]]:
-~ This is the first term we will define.
-
-[[def: Term 2, Term Two]]:
-~ This is the second term, but not the last.
-
-[[def: Term 3, Term Three]]:
-~ This is the last term, because you know what they say: third term's the charm!
-
-
-
Term 1:
-
This is the first term we will define.
-
Term 2:
-
This is the second term, but not the last.
-
Term 3:
-
This is the last term, because you know what they say: third term’s the charm!
-
-

Now let’s refer to some of the terms defined above to show how the auto-linking of terms works: Term 1, Term Two, Term 3. Additionally, as long as you define your terms using Definition Lists (as seen in the markdown above), you will be able to hover any reference to a term to see a tooltip with its definition.

-

§ Table-defined Terms

-

You can also reference table-oriented terms and definitions which are decomposed into heading-titled attributes in distinct cells:

-
-Variable           | Default Value | Max Value
-------------------- | -------------- | ---------
-[[def: Variable 1]] | 123          | 9999
-
- - - - - - - - - - - - - - - -
VariableDefault ValueMax Value
Variable 11239999
-

Anytime you add a definition of a term in the first column of a table, like Variable 1, it will link to the cell and display a tooltip with the entire set of row values when you hover the term.

-

§ External Term References

-

It is possible to include references to terms from external spec-up generated specifications. To include a source you would like to pull references from include an external_specs array in your spec config. The value should be a key/value object where the key is used in the external reference below and the value is the URL of the external spec.

-
EXAMPLE
{
-  "specs": [
-    {
-      ...
-      "external_specs": [
-        {"PE": "https://identity.foundation/presentation-exchange"}
-      ]
-    }
-  ]
-}
-
-
-

To include an external term reference within your spec use the following format [[xref: {title}, {term}]] where {title} is the title given to the spec in the config and {term} is the term being used. For example using the PE spec given in the example above Holder

-

§ Blockquote

-
-

To be, or not to be, that is the question: -Whether 'tis nobler in the mind to suffer -The slings and arrows of outrageous fortune, -Or to take arms against a sea of troubles -And by opposing end them. To die—to sleep, -No more;

-
-

§ Notices

-
-::: note Basic Note
-  Check this out.
-:::
-
-
NOTE

Check this out.

-
-
NOTE

Here’s another.

-
-
NOTE

And one more!

-
-
NOTE

One last note!!!

-
-
-::: issue Issue Notice
-  I take issue with that, kind sir.
-:::
-
-
ISSUE

I take issue with that, kind sir.

-
-
-::: warning Warning Notice
-  Houston, I think we have a problem
-:::
-
-
WARNING

Houston, I think we have a problem

-
-
-::: todo Really Important
-  Get this done!
-:::
-
-
TODO

Get this done!

-
-
-::: example Code Example
-  Put your code block here
-:::
-
-
EXAMPLE
// Some comment in JSON
-{
-  "foo": "bar",
-  "baz": 2
-}
+
The mining company determines what VCs it wants to publish in its /whois VP,
+and the importer resolving the DPP can resolve “up the hierarchy” of the various
+VCs to find the authorities issuing the collection of VCs. In the end, the
+importer software may recognize and trust the authorities issuing the VCs and
+make a trust decision on the mining company. If not, the software can take the
+collected information (VCs and issuers) and pass that along to a person to make
+the trust decision.

+
§ Decentralized Trust Registry

+
The /whois path enables:

+
    
+
  • Verification of entities across multiple domains using cryptographic proofs.
    • 
+
  • Automated or manual trust decisions based on retrieved information.
    • 
+
  • Efficient and decentralized trust establishment comparable to a Certificate Authority hierarchy but self-managed by DID Controllers and issuers.
    • 
+

+
§ Implementation Details

+
§ DID URL Syntax

+
The /whois path conforms to the following syntax:

+
<did>/whois
 

-
-

§ Content Insertion

-

Use the following format to pull in content from other files in your project:

-
-This text has been inserted here from another file: [[insert: ./single-file-test/assets/test.text]]
-
-

This text has been inserted here from another file: Beam me in, Scotty!

-

You can even insert content within more complex blocks, like the JSON object below which is being pulled in and rendered in a syntax-highlighted example block:

-
-::: example Code Example
-```json
-[[insert: ./single-file-test/assets/test.json]]
-```
-:::
-
-
EXAMPLE
{
-  "foo": {
-    "bar": 1
+
§ Resolution Process

+
    
+
  1. Resolve the DID and retrieve and verify the DIDDoc.
    2. 
+
  2. Locate the <did>#whois service in the resolved DID Document. This service MUST be of type LinkedVerifiablePresentation.
+
      
+
    1. A DID Method MAY define an implicit #whois service that useful for that DID Method. For example, the [DIDWEBVH] DID Method has a DID-to-HTTPS-URL transformation used when resolving the DIDDoc, and implicitly defines a #$whois service that uses the same DID-to-HTTPS transformation to define the location of the whois.vp resource. A DID Controller MAY explicitly include a #whois service in their DID Document, overriding the implicit #whois service.
      2. 
+
    
+
    3. 
+
  3. Resolve the serviceEndpoint to obtain the Verifiable Presentation.
    4. 
+
  4. Verify the VP and the VCs in the VP.
    5. 
+
  5. Parse the VP to extract Verifiable Credentials and associated metadata.
    6. 
+
  6. Optionally resolve the /whois path of issuers of the VCs for further trust validation as needed and available.
    7. 
+

+
§ Example DID Document Service Item

+
The resolved DID Document must include a service item for /whois as follows:

+
"service": [
+  {
+    "id": "did:example:123#whois",
+    "type": "LinkedVerifiablePresentation",
+    "serviceEndpoint": "https://bar.example.com/whois.vp"
   }
-}
+]
 

-
-

§ Tables

-
-Stage | Direct Products | ATP Yields
-----: | --------------: | ---------:
-Glycolysis | 2 ATP ||
-^^ | 2 NADH | 3--5 ATP |
-Pyruvaye oxidation | 2 NADH | 5 ATP |
-Citric acid cycle | 2 ATP ||
-^^ | 6 NADH | 15 ATP |
-^^ | 2 FADH2 | 3 ATP |
-**30--32** ATP |||
-[Net ATP yields per hexose]
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Net ATP yields per hexose
StageDirect ProductsATP Yields
Glycolysis2 ATP
2 NADH3–5 ATP
Pyruvaye oxidation2 NADH5 ATP
Citric acid cycle2 ATP
6 NADH15 ATP
2 FADH23 ATP
30–32 ATP
-
-|--|--|--|--|--|--|--|--|
-|♜|  |♝|♛|♚|♝|♞|♜|
-|  |♟|♟|♟|  |♟|♟|♟|
-|♟|  |♞|  |  |  |  | |
-|  |♗|  |  |♟|  |  | |
-|  |  |  |  |♙|  |  | |
-|  |  |  |  |  |♘|  | |
-|♙|♙|♙|♙|  |♙|♙|♙|
-|♖|♘|♗|♕|♔|  |  |♖|
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
♜♝♛♚♝♞♜
♟♟♟♟♟♟
♟♞
♗♟
♙
♘
♙♙♙♙♙♙♙
♖♘♗♕♔♖
-

§ Sequence Diagrams

-
-```mermaid
-sequenceDiagram
-  Alice ->> Bob: Hello Bob, how are you?
-  Bob-->>John: How about you John?
-  Bob--x Alice: I am good thanks!
-  Bob-x John: I am good thanks!
-  Note right of John: Bob thinks a long
long time, so long
that the text does
not fit on a row.
-
-  Bob-->Alice: Checking with John...
-  Alice->John: Yes... John, how are you?
-```
-
-
-sequenceDiagram - Alice ->> Bob: Hello Bob, how are you? - Bob-->>John: How about you John? - Bob--x Alice: I am good thanks! - Bob-x John: I am good thanks! - Note right of John: Bob thinks a long
long time, so long
that the text does
not fit on a row. - - Bob-->Alice: Checking with John... - Alice->John: Yes... John, how are you? -
-

§ Flows

-
-```mermaid
-graph TD
-  A[Start] --> B{Is it?}
-  B -->|Yes| C[OK]
-  C --> D[Rethink]
-  D --> B
-  B -->|No| E[End]
-```
-
-
-graph TD - A[Start] --> B{Is it?} - B -->|Yes| C[OK] - C --> D[Rethink] - D --> B - B -->|No| E[End] -
-

§ Charts

-
-```chart
-{
-  "type": "pie",
-  "data": {
-    "labels": [
-      "Red",
-      "Blue",
-      "Yellow"
-    ],
-    "datasets": [
-      {
-        "data": [
-          300,
-          50,
-          100
-        ],
-        "backgroundColor": [
-          "#FF6384",
-          "#36A2EB",
-          "#FFCE56"
-        ],
-        "hoverBackgroundColor": [
-          "#FF6384",
-          "#36A2EB",
-          "#FFCE56"
-        ]
-      }
-    ]
-  }
-}
-```
-
-{"type":"pie","data":{"labels":["Red","Blue","Yellow"],"datasets":[{"data":[300,50,100],"backgroundColor":["#FF6384","#36A2EB","#FFCE56"],"hoverBackgroundColor":["#FF6384","#36A2EB","#FFCE56"]}]}}

§ Syntax Highlighting

-
-```json
-{
-  "@context": "https://www.w3.org/ns/did/v1",
-  "id": "did:example:123456789abcdefghi",
-  "authentication": [{
-    "id": "did:example:123456789abcdefghi#keys-1",
-    "type": "RsaVerificationKey2018",
-    "controller": "did:example:123456789abcdefghi",
-    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
-  }],
-  "service": [{
-    "id":"did:example:123456789abcdefghi#vcs",
-    "type": "VerifiableCredentialService",
-    "serviceEndpoint": "https://example.com/vc/"
-  }]
-}
-```
-
-
{
-  "@context": "https://www.w3.org/ns/did/v1",
-  "id": "did:example:123456789abcdefghi",
-  "authentication": [{ 
-    "id": "did:example:123456789abcdefghi#keys-1",
-    "type": "RsaVerificationKey2018",
-    "controller": "did:example:123456789abcdefghi",
-    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
-  }],
-  "service": [{
-    "id":"did:example:123456789abcdefghi#vcs",
-    "type": "VerifiableCredentialService",
-    "serviceEndpoint": "https://example.com/vc/"
-  }]
-}
-
-

§ TeX Math Equations

-

When the katex option is enabled, the KaTeX math engine is used for TeX rendering. You can find a list of supported features and examples here: https://katex.org/docs/supported.html.

-

(x2y2)=(ABCD)⋅(x1y1)\begin{pmatrix}x_2 \\ y_2 \end{pmatrix} = -\begin{pmatrix} A & B \\ C & D \end{pmatrix}\cdot -\begin{pmatrix} x_1 \\ y_1 \end{pmatrix}

-

abcdefghi\def\arraystretch{1.5} - \begin{array}{c:c:c} - a & b & c \\ \hline - d & e & f \\ - \hdashline - g & h & i -\end{array}

-

a+b+c⏟Note: such math, much wow.\underbrace{a+b+c}_{\text{Note: such math, much wow.}} -

-

§ Tab Panels

- - -
-
{
-  "foo": "foo",
-  "baz": 1
-}
-
-
-
-
{
-  "foo": "bar",
-  "baz": 2
-}
-
-
- - -

Spec-Up automatically upgrades the links of certain sites, like GitHub. GitHub is the only supported site with Fancy Links right now, but we’ll be adding more as we go.

-

§ GitHub

+

§ Verifiable Presentation Requirements

    -
  • Issues +
  • The returned whois.vp MUST contain a W3C Verifiable Presentation signed by the DID.
    • +
  • At least one of the Verifiable Credentials within the VP MUST use the DID as the credentialSubject.
      -
    • Source: https://github.com/decentralized-identity/presentation-exchange/issues/119
      • -
    • Render: https://github.com/decentralized-identity/presentation-exchange/issues/119
      • +
    • Such a VC MAY attest to the binding of other identifiers to the DID. For example, the VC may be from an authority that attests to the legal name and registration identifier of the entity controlling the DID.
    • -
  • Pull Requests +
  • The credentialSubject of other VCs may be identifiers cryptographically bound in other VCs within the VP to the DID being resolved.
      -
    • Source: https://github.com/decentralized-identity/sidetree/pull/863
      • -
    • Render: https://github.com/decentralized-identity/sidetree/pull/863
      • +
    • For example, the legal name or legal entity registration identifier could be the credentialSubject if another VC in the VP binds that identifier to the DID.
    • -
  • Releases +
  • The DID Controller determines which Verifiable Credentials to include based on their usefulness for establishing the identity and trustworthiness of the entity controlling the DID.
    • +
  • The resolver determines which Verifiable Credentials are useful in its determination of the identity and trustworthiness of the entity controlling the DID.
    • +
+

What Verifiable Credentials and who should issue those credentials are outside +of the scope of this specification. A future version of the specification may +define at least a credential that binds the DID to the other identifiers used +by/assigned to the legal entity controlling the DID. For example, the +United Nations Transparency Protocol’s Digital Identity Anchor might be a good +candidate for a standard VC to bind the DID to the legal entity of the +controller.

+

§ Error Handling

+

Resolvers MUST handle errors as follows:

    -
  • Source: https://github.com/decentralized-identity/sidetree/releases/tag/v0.9.1
    • -
  • Render: https://github.com/decentralized-identity/sidetree/releases/tag/v0.9.1
    • +
  • If the serviceEndpoint cannot be resolved, return Error 404: Not Found.
    • +
  • If the file at the defined serviceEndpoint is not found, return Error 404: Not Found.
    • +
  • If the VP fails verification, return Error 500: Server Error.
- -
  • Projects +

    § Security and Privacy Considerations

    +
      +
    • Data Minimization:
      • +
    • Cryptographic Integrity: +
        +
      • All returned VPs must be signed by the DID Controller.
      -

      § External Spec References

      -

      You can reference external specifications from IETF, W3C, and WHATWG as follows:

      -
        -
      1. Anywhere in your document you want to referece an external specification, use the spec-prefixed custom token format: [[spec:RFC4122]]
        2. -
      2. Wherever in your document you want to print out all your external specification references, use the spec custom token format without any spec name: [[spec]]
        3. -
      +
      • +
    • Access Control:
        -
      • If you want to split up your references into groups (e.g. normative vs informative), just make sure to use dash-delimited unique reference grouping string in your custom tokens: [[spec-norm:RFC4122]], [[spec-inform:RFC4122]], [[spec-foo:RFC4122]], etc.
        • -
      • To print out a custom group’s references, just include the grouping string for a given set of references in a custom token without any spec name: [[spec-norm]], [[spec-inform]], [[spec-foo]].
        • +
      • There is not an intention to limit access to the /whois service endpoint. It is the responsibility of the DID Controller to ensure that only Verifiable Presentations containing public information are published at the service endpoint.
        • +
      • Personally identifiable information (PII) MUST NOT be published to the <did>/whois service endpoint.
      -

      Here are a set of example references that are distributed among the reference groups spec, spec-norm, spec-inform:

      +
      • +
    • Exposing Sensitive Information:
        -
      • [RFC3548] ([[spec:RFC3548]])
        • -
      • [RFC7518] ([[spec:RFC7518]])
        • -
      • [DID-CORE] ([[spec-norm:DID-CORE]])
        • -
      • [DID-SPEC-REGISTRIES] ([[spec-norm:DID-SPEC-REGISTRIES]])
        • -
      • [RFC6901] ([[spec-inform:RFC6901]])
        • -
      • [RFC7230] ([[spec-inform:RFC7230]])
        • +
      • Careful scoping of /whois data is necessary to avoid unintentional disclosure.
      -

      § Default References

      -

      This is what is printed out when you include the [[spec]] custom token in your Markdown:

      -

      -

      -
      RFC3548
      -
      - The Base16, Base32, and Base64 Data Encodings. - S. Josefsson, Ed.; 2003-07. Status: Informational. -
      - -
      RFC7518
      -
      - JSON Web Algorithms (JWA). - M. Jones; 2015-05. Status: Proposed Standard. -
      - +
      • +
    +

    § Conclusion

    +

    The /whois path standardizes a decentralized mechanism for retrieving verifiable information about DIDs. It empowers trust decisions through cryptographic verification and promotes interoperability across decentralized systems.

    +

    § Definitions

    +
    +
    DID Controller
    +
    The DID Controller is the entity that has the authority to update its DID. In +the context of this specification, the DID Controller is the entity +represented by the DID. The <did>/whois capability will most often be used +by legal entities that want to establish a Verifiable Credential-backed +linkage between their DID and their legal entity, attested to be a suitable +authority.
    +
    W3C Verifiable Presentation
    +
    A Verifiable Presentation as defined in the W3C [[spec:vcdm]].
    -

    -

    § Normative References

    -

    This is what is printed out when you include the [[spec-norm]] custom token in your Markdown:

    +

    § References

    +

    -
    DID-CORE
    -
    - Decentralized Identifiers (DIDs) v1.0. - Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed; 2022-07-19. Status: REC. -
    - -
    DID-SPEC-REGISTRIES
    +
    DIDWEBVH
    - DID Specification Registries. - Orie Steele; Manu Sporny; 2023-09-11. Status: NOTE. + did:webvh DID Method. + Stephen Curran; John Jordan; Brian Richter; Andrew Whitehead; Michel Sahli; Martina Kolpondinos; Dmitri Zagdulin; 2024-12-20. Status: Draft.
    -
    -

    -

    § Informative References

    -

    This is what is printed out when you include the [[spec-inform]] custom token in your Markdown:

    -

    -

    -
    RFC6901
    +
    LINKED-VP
    - JavaScript Object Notation (JSON) Pointer. - P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.; 2013-04. Status: Proposed Standard. + Linked Verifiable Presentation v1.0.0. + Jan Christoph Ebersbach; Brian Richter; Markus Sabadello; 2024-07-03. Status: DIF Ratified Specification.
    -
    RFC7230
    +
    RFC3912
    - Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. - R. Fielding, Ed.; J. Reschke, Ed.; 2014-06. Status: Proposed Standard. + WHOIS Protocol Specification. + L. Daigle; 2004-09. Status: Draft Standard.
    @@ -681,37 +300,29 @@

    • Abstract
      • -
    • Getting Started
      • -
    • Table of Contents
      • -
    • Term References +
    • Introduction @@ -719,97 +330,10 @@

      -
      Claim
      An assertion made about a Subject. Used as an umbrella term for -Credential, Assertion, Attestation, etc.
      Claim
      An assertion made about a Subject. Used as an umbrella term for -Credential, Assertion, Attestation, etc.
      Conformant Consumer
      An entity that follows the specified processing rules to consume a -Presentation Definition or Presentation Submission that conforms -to this specification.
      Conformant Consumer
      An entity that follows the specified processing rules to consume a -Presentation Definition or Presentation Submission that conforms -to this specification.
      Conformant Producer
      An entity that produces a Presentation Definition or -Presentation Submission that conforms to this specification.
      Embed Locations
      Embed Locations are the specific paths and indexes per Embed Target -where the Verifier can expect to find the Presentation. See Embed Locations.
      Embed Target
      Embed Targets are data formats used in messaging protocols that may be used -to transport a Presentation Submission. See -Embed Targets.
      Embed Target
      Embed Targets are data formats used in messaging protocols that may be used -to transport a Presentation Submission. See -Embed Targets.
      Feature
      Features enable Verifiers to express, and Holders to support, -extended functionality (relative to the base objects) by defining one or more -properties on one or more objects.
      Feature
      Features enable Verifiers to express, and Holders to support, -extended functionality (relative to the base objects) by defining one or more -properties on one or more objects.
      Holder
      Holders are entities that submit proofs to Verifiers to satisfy the -requirements described in a Presentation Definition. A Holder is a -Conformant Consumer of a Presentation Definition and a -Conformant Producer of a Presentation Submission.
      Holder
      Holders are entities that submit proofs to Verifiers to satisfy the -requirements described in a Presentation Definition. A Holder is a -Conformant Consumer of a Presentation Definition and a -Conformant Producer of a Presentation Submission.
      Holder Binding
      Holder Bindings are requirements of a certain type of relationship between -the Holder and the Claims within the Presentation. See Holder Binding.
      Decentralized Web Node
      Some examples refer to an unfamiliar query protocol, dwn://, as a way of -storing and querying schemata and other resources. While orthogonal to this -specification and not yet on a standards track, the concept of “decentralized web nodes” -proposes an architecture that may be of interest or utility to implementers of -this specification. For more information, see the draft specification -hosted at the decentralized identity foundation -here
      Decentralized Web Node
      Some examples refer to an unfamiliar query protocol, dwn://, as a way of -storing and querying schemata and other resources. While orthogonal to this -specification and not yet on a standards track, the concept of “decentralized web nodes” -proposes an architecture that may be of interest or utility to implementers of -this specification. For more information, see the draft specification -hosted at the decentralized identity foundation -here
      Input Descriptor
      Input Descriptors are used by a Verifier to describe the information required -of a Holder before an interaction can proceed. See -Input Descriptor.
      Input Descriptor
      Input Descriptors are used by a Verifier to describe the information required -of a Holder before an interaction can proceed. See -Input Descriptor.
      Input Descriptor Object
      Input Descriptors Objects are populated with properties describing what type -of input data/Claim, or sub-fields thereof, are required for submission -to the Verifier. See -Input Descriptor Object.
      Input Descriptor Object
      Input Descriptors Objects are populated with properties describing what type -of input data/Claim, or sub-fields thereof, are required for submission -to the Verifier. See -Input Descriptor Object.
      Link Secrets
      Link Secrets are values held by the Holder but hidden from other -parties. They are typically incorporated into cryptographic signatures used in -claims to demonstrate correlation while preventing replay attacks. An Issuer -may ascertain that a Holder possesses a link secret without its disclosure. -See Link Secrets.
      Presentation Definition
      Presentation Definitions are objects that articulate what proofs a Verifier -requires. These help the Verifier to decide how or whether to interact with a -Holder. Presentation Definitions are composed of inputs, which describe -the forms and details of the proofs they require, and optional sets of -selection rules, to allow Holders flexibility in cases where many different -types of proofs may satisfy an input requirement. See -Presentation Definition.
      Presentation Request
      Presentation Requests are transport mechanisms for Presentation. Presentation Requests can take multiple shapes, using a variety -of protocols and signature schemes not refined in this specification. They are -sent by a Verifier to a Holder. Defining Presentation Requests -is outside the scope of this specification. See -Presentation Request.
      Presentation Submission
      Presentation Submissions are objects embedded within target claim negotiation -formats that unify the presentation of proofs to a Verifier in -accordance with the requirements a Verifier specified in a -Presentation Definition. See -Presentation Submission.
      Subject
      Subjects are the entities about which Claims are made. The Subject may -not be the same entity as the Holder
      Subject
      Subjects are the entities about which Claims are made. The Subject may -not be the same entity as the Holder
      Submission Requirement
      Submission Requirements are objects that define what combinations of inputs -must be submitted to comply with the requirements a Verifier has for -proceeding in a flow (e.g. credential issuance, allowing entry, accepting an -application). See Submission Requirements.
      Submission Requirement
      Submission Requirements are objects that define what combinations of inputs -must be submitted to comply with the requirements a Verifier has for -proceeding in a flow (e.g. credential issuance, allowing entry, accepting an -application). See Submission Requirements.
      Submission Requirement Object
      Submission Requirement Objects describe valid combinations of inputs in a -Presentation Submission. See -Submission Requirement Objects.
      Submission Requirement Object
      Submission Requirement Objects describe valid combinations of inputs in a -Presentation Submission. See -Submission Requirement Objects.
      Submission Requirement Rule
      Submission Requirement Rules describe combinatorial rules within a -Submission Requirement Object when processing inputs. They may be -nested. See Submission Requirement Rules.
      Submission Requirement Rule
      Submission Requirement Rules describe combinatorial rules within a -Submission Requirement Object when processing inputs. They may be -nested. See Submission Requirement Rules.
      Verifier
      Verifiers are entities that define what proofs they require from a -Holder (via a Presentation Definition) in order to proceed with -an interaction. A Verifier is a Conformant Producer of a -Presentation Definition and a Conformant Consumer of a -Presentation Submission.
      Verifier
      Verifiers are entities that define what proofs they require from a -Holder (via a Presentation Definition) in order to proceed with -an interaction. A Verifier is a Conformant Producer of a -Presentation Definition and a Conformant Consumer of a -Presentation Submission.
      OIDC
      Open ID Connect. Jones, M., Bradley, J., and N. Sakimura. Status: Approved Specification
      Linked Data Proof
      Data Integrity 1.0. Dave Longley, Manu Sporny. 2022-03. Status: Draft Community Group Report.
      Linked Data Proof
      Data Integrity 1.0. Dave Longley, Manu Sporny. 2022-03. Status: Draft Community Group Report.
      CHAPI
      W3C Credential Handler API 1.0. Dave Longley, Manu Sporny. 2020-2-19. Status: Draft Community Group Report.
      CHAPI
      W3C Credential Handler API 1.0. Dave Longley, Manu Sporny. 2020-2-19. Status: Draft Community Group Report.
      DIDComm
      DIF DIDComm Messaging. Daniel Hardman, Sam Curren. Status: Working Group Draft.
      + - + - \ No newline at end of file diff --git a/index.js b/index.js deleted file mode 100644 index 1e23882..0000000 --- a/index.js +++ /dev/null @@ -1,366 +0,0 @@ - -module.exports = function(options = {}) { - - const { - fetchExternalSpecs, - validateReferences, - findExternalSpecByKey - } = require('./references.js'); - const gulp = require('gulp'); - const fs = require('fs-extra'); - const path = require('path'); - const findPkgDir = require('find-pkg-dir'); - const modulePath = findPkgDir(__dirname); - let config = fs.readJsonSync('./specs.json'); - let assets = fs.readJsonSync(modulePath + '/src/asset-map.json'); - let externalReferences; - let references = []; - let definitions = []; - - const katexRules = ['math_block', 'math_inline'] - const replacerRegex = /\[\[\s*([^\s\[\]:]+):?\s*([^\]\n]+)?\]\]/img; - const replacerArgsRegex = /\s*,+\s*/; - const replacers = [ - { - test: 'insert', - transform: function(path){ - if (!path) return ''; - return fs.readFileSync(path, 'utf8'); - } - } - ]; - - function applyReplacers(doc){ - return doc.replace(replacerRegex, function(match, type, args){ - let replacer = replacers.find(r => type.trim().match(r.test)); - return replacer ? replacer.transform(...args.trim().split(replacerArgsRegex)) : match; - }); - } - - function normalizePath(path){ - return path.trim().replace(/\/$/g, '') + '/'; - } - - function renderRefGroup(type){ - let group = specGroups[type]; - if (!group) return ''; - let html = Object.keys(group).sort().reduce((html, name) => { - let ref = group[name]; - return html += ` -
      ${name}
      -
      - ${ref.title}. - ${ref.authors.join('; ')}; ${ref.rawDate}. Status: ${ref.status}. -
      - `; - }, '
      ') - return `\n${html}\n
      \n`; - } - - function findKatexDist(){ - const relpath = "node_modules/katex/dist"; - const paths = [ - path.join(process.cwd(), relpath), - path.join(__dirname, relpath), - ]; - for(const abspath of paths) { - if(fs.existsSync(abspath)) { - return abspath - } - } - throw Error("katex distribution could not be located"); - } - - try { - - var toc; - var specGroups = {}; - const noticeTypes = { - note: 1, - issue: 1, - example: 1, - warning: 1, - todo: 1 - }; - const spaceRegex = /\s+/g; - const specNameRegex = /^spec$|^spec[-]*\w+$/i; - const terminologyRegex = /^def$|^ref$|^xref/i; - const specCorpus = fs.readJsonSync(modulePath + '/assets/compiled/refs.json'); - const containers = require('markdown-it-container'); - const md = require('markdown-it')({ - html: true, - linkify: true, - typographer: true - }) - .use(require('./src/markdown-it-extensions.js'), [ - { - filter: type => type.match(terminologyRegex), - parse(token, type, primary){ - if (!primary) return; - if (type === 'def'){ - definitions.push(token.info.args); - return token.info.args.reduce((acc, syn) => { - return `${acc}`; - }, primary); - } - else if (type === 'xref') { - const url = findExternalSpecByKey(config, token.info.args[0]); - const term = token.info.args[1].replace(spaceRegex, '-').toLowerCase(); - return `${token.info.args[1]}`; - } - else { - references.push(primary); - return `${primary}`; - } - } - }, - { - filter: type => type.match(specNameRegex), - parse(token, type, name){ - if (name) { - let _name = name.replace(spaceRegex, '-').toUpperCase(); - let spec = specCorpus[_name] || - specCorpus[_name.toLowerCase()] || - specCorpus[name.toLowerCase()] || - specCorpus[name]; - if (spec) { - spec._name = _name; - let group = specGroups[type] = specGroups[type] || {}; - token.info.spec = group[_name] = spec; - } - } - }, - render(token, type, name){ - if (name){ - let spec = token.info.spec; - if (spec) return `[${spec._name}]`; - } - else return renderRefGroup(type); - } - } - ]) - .use(require('markdown-it-attrs')) - .use(require('markdown-it-chart').default) - .use(require('markdown-it-deflist')) - .use(require('markdown-it-references')) - .use(require('markdown-it-icons').default, 'font-awesome') - .use(require('markdown-it-ins')) - .use(require('markdown-it-mark')) - .use(require('markdown-it-textual-uml')) - .use(require('markdown-it-sub')) - .use(require('markdown-it-sup')) - .use(require('markdown-it-task-lists')) - .use(require('markdown-it-multimd-table'), { - multiline: true, - rowspan: true, - headerless: true - }) - .use(containers, 'notice', { - validate: function(params) { - let matches = params.match(/(\w+)\s?(.*)?/); - return matches && noticeTypes[matches[1]]; - }, - render: function (tokens, idx) { - let matches = tokens[idx].info.match(/(\w+)\s?(.*)?/); - if (matches && tokens[idx].nesting === 1) { - let id; - let type = matches[1]; - if (matches[2]) { - id = matches[2].trim().replace(/\s+/g , '-').toLowerCase(); - if (noticeTitles[id]) id += '-' + noticeTitles[id]++; - else noticeTitles[id] = 1; - } - else id = type + '-' + noticeTypes[type]++; - return `
      ${type.toUpperCase()}`; - } - else return '
      \n'; - } - }) - .use(require('markdown-it-prism')) - .use(require('markdown-it-toc-and-anchor').default, { - tocClassName: 'toc', - tocFirstLevel: 2, - tocLastLevel: 4, - tocCallback: (_md, _tokens, html) => toc = html, - anchorLinkSymbol: '§', - anchorClassName: 'toc-anchor' - }) - .use(require('@traptitech/markdown-it-katex')) - - async function render(spec, assets) { - try { - noticeTitles = {}; - specGroups = {}; - console.log('Rendering: ' + spec.title); - return new Promise(async (resolve, reject) => { - Promise.all((spec.markdown_paths || ['spec.md']).map(_path => { - return fs.readFile(spec.spec_directory + _path, 'utf8').catch(e => reject(e)) - })).then(async docs => { - const features = (({ source, logo }) => ({ source, logo }))(spec); - if (spec.external_specs && !externalReferences) { - externalReferences = await fetchExternalSpecs(spec); - } - let doc = docs.join("\n"); - doc = applyReplacers(doc); - md[spec.katex ? "enable" : "disable"](katexRules); - const render = md.render(doc); - fs.writeFile(path.join(spec.destination, 'index.html'), ` - - - - - - - - ${spec.title} - - - - ${assets.head} - - - - ${assets.svg} - -
      - - - -
      - ${render} -
      - -
      - - - -
      - - - - - ✕ -
      -
        -         - - -
        - Table of Contents - ✕ -
        -
        - ${toc} -
        -         - -         -
        - ${externalReferences} -
        - - - ${assets.body} - - `, function(err, data){ - if (err) { - reject(err); - } - else { - resolve(); - } - }); - validateReferences(references, definitions, render); - references = []; - definitions = []; - }); - }); - } - catch(e) { - console.error(e); - } - } - - config.specs.forEach(spec => { - spec.spec_directory = normalizePath(spec.spec_directory); - spec.destination = normalizePath(spec.output_path || spec.spec_directory); - - fs.ensureDirSync(spec.destination); - - let assetTags = { - svg: fs.readFileSync(modulePath + '/assets/icons.svg', 'utf8') || '' - }; - - let customAssets = (spec.assets || []).reduce((assets, asset) => { - let ext = asset.path.split('.').pop(); - if (ext === 'css') { - assets.css += ``; - } - if (ext === 'js') { - assets.js[asset.inject || 'body'] += ``; - } - return assets; - }, { - css: '', - js: { head: '', body: '' } - }); - - if (options.dev) { - assetTags.head = assets.head.css.map(_path => ``).join('') + - customAssets.css + - assets.head.js.map(_path => ``).join('') + - customAssets.js.head; - assetTags.body = assets.body.js.map(_path => ``).join('') + - customAssets.js.body; - } - else { - assetTags.head = ` - - ${ customAssets.css } - - ${ customAssets.js.head } - `; - assetTags.body = ` - ${ customAssets.js.body }`; - } - - if (spec.katex) { - const katexDist = findKatexDist(); - assetTags.body += ``; - assetTags.body += ``; - - fs.copySync(path.join(katexDist, 'fonts'), path.join(spec.destination, 'fonts')); - } - - if (!options.nowatch) { - gulp.watch( - [spec.spec_directory + '**/*', '!' + path.join(spec.destination, 'index.html')], - render.bind(null, spec, assetTags) - ) - } - - render(spec, assetTags).then(() => { - if (options.nowatch) process.exit(0) - }).catch(() => process.exit(1)); - - }); - - } - catch(e) { - console.error(e); - } - -} \ No newline at end of file diff --git a/multi-file-test/abstract.md b/multi-file-test/abstract.md deleted file mode 100644 index f0c0f3f..0000000 --- a/multi-file-test/abstract.md +++ /dev/null @@ -1,3 +0,0 @@ -## Abstract - -Let's face it, other tools and generators for writing technical specifications aimed at standards bodies or industry groups are cumbersome, underwhelming, and lack the features you might want in a technical specification document. Spec-Up's goal is to deliver you a better spec-writing experience with far less effort and tedium than other tools in the ecosystem. Spec-Up is a dead simple tool that auto-generates great specs from markdown. The version of markdown Spec-up uses contains all the same features you might expect from common implementations, like GitHub, but adds much more, including notice blocks, complex tables, charts, advanced syntax highlighting, UML diagrams, etc. \ No newline at end of file diff --git a/multi-file-test/features.md b/multi-file-test/features.md deleted file mode 100644 index 71950fc..0000000 --- a/multi-file-test/features.md +++ /dev/null @@ -1,132 +0,0 @@ -## Features - -### Diagrams -
        -```mermaid
-sequenceDiagram
-  participant Alice
-  participant Bob
-  Alice->>Bob: Hey Bob
-  Bob-->>Alice: Great!
-  Alice->>Bob: How about you?
-  Bob-->>Alice: Doing well!
-```
-
        - -```mermaid -sequenceDiagram - participant Alice - participant Bob - Alice->>Bob: Hey Bob - Bob-->>Alice: Great! - Alice->>Bob: How about you? - Bob-->>Alice: Doing well! -``` - -### Charts - -
        -```chart
-{
-  "type": "pie",
-  "data": {
-    "labels": [
-      "Red",
-      "Blue",
-      "Yellow"
-    ],
-    "datasets": [
-      {
-        "data": [
-          300,
-          50,
-          100
-        ],
-        "backgroundColor": [
-          "#FF6384",
-          "#36A2EB",
-          "#FFCE56"
-        ],
-        "hoverBackgroundColor": [
-          "#FF6384",
-          "#36A2EB",
-          "#FFCE56"
-        ]
-      }
-    ]
-  }
-}
-```
-
        - -```chart -{ - "type": "pie", - "data": { - "labels": [ - "Red", - "Blue", - "Yellow" - ], - "datasets": [ - { - "data": [ - 300, - 50, - 100 - ], - "backgroundColor": [ - "#FF6384", - "#36A2EB", - "#FFCE56" - ], - "hoverBackgroundColor": [ - "#FF6384", - "#36A2EB", - "#FFCE56" - ] - } - ] - } -} -``` - -### Syntax Highlighting - -
        -```json
-{
-  "@context": "https://www.w3.org/ns/did/v1",
-  "id": "did:example:123456789abcdefghi",
-  "authentication": [{
-    "id": "did:example:123456789abcdefghi#keys-1",
-    "type": "RsaVerificationKey2018",
-    "controller": "did:example:123456789abcdefghi",
-    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
-  }],
-  "service": [{
-    "id":"did:example:123456789abcdefghi#vcs",
-    "type": "VerifiableCredentialService",
-    "serviceEndpoint": "https://example.com/vc/"
-  }]
-}
-```
-
        - -```json -{ - "@context": "https://www.w3.org/ns/did/v1", - "id": "did:example:123456789abcdefghi", - "authentication": [{ - "id": "did:example:123456789abcdefghi#keys-1", - "type": "RsaVerificationKey2018", - "controller": "did:example:123456789abcdefghi", - "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n" - }], - "service": [{ - "id":"did:example:123456789abcdefghi#vcs", - "type": "VerifiableCredentialService", - "serviceEndpoint": "https://example.com/vc/" - }] -} -``` \ No newline at end of file diff --git a/multi-file-test/getting-started.md b/multi-file-test/getting-started.md deleted file mode 100644 index f0cf841..0000000 --- a/multi-file-test/getting-started.md +++ /dev/null @@ -1,21 +0,0 @@ -## Getting Started - -Using Spec-Up is easy peasy lemon squeezy: - -1. `npm install spec-up` -2. Create a subdirectory in your project with two files: - - `spec.json` - add some basic config values, like your desired HTML page title, etc. - - `spec.md` - write the markdown version of your spec here (duh) -3. In your main node.js file, drop in this bad boy: `require('spec-up')()` - -Boom! That's it. Spec-Up will auto-detect the location of your spec files and auto-generate your spec's HTML version every time you hit save after editing your `spec.md` files. Did I mention you can have multiple specs located at any depth in your project and Spec-Up will crawl up in there and render all those specs like a damn boss? Well it does, because why the hell not. - -**Usage** - -If your `spec.json` and `package.json` and `package-lock.json` files are in working order, Spec-up can be called from the root of your repo in three different modes: - -|command|behavior| -|---|---| -|`npm run edit`|after rendering, this will stay running and the `gulp` library will watch the source files in your spec directory/ies for changes and re-render any time you save a file. Opening these rendered files in a browser and refreshing them will keep you up to date.| -|`npm run render`|this renders the site once and does not keep a gulpy watch on the underlying files.| -|`npm run dev`|this enables debugging features.| \ No newline at end of file diff --git a/multi-file-test/header.md b/multi-file-test/header.md deleted file mode 100644 index 7ef12ad..0000000 --- a/multi-file-test/header.md +++ /dev/null @@ -1,17 +0,0 @@ -Spec-Up Multi-File Example -================== - -**Specification Status:** Strawman - -**Latest Draft:** - [https://github.com/decentralized-identity/spec-up](https://github.com/decentralized-identity/spec-up) - -**Editors:** -~ [Daniel Buchner](https://www.linkedin.com/in/dbuchner/) - -**Participate:** -~ [GitHub repo](https://github.com/csuwildcat/spec-up) -~ [File a bug](https://github.com/csuwildcat/spec-up/issues) -~ [Commit history](https://github.com/csuwildcat/spec-up/commits/master) - ------------------------------------- diff --git a/multi-file-test/index.html b/multi-file-test/index.html deleted file mode 100644 index 2d21994..0000000 --- a/multi-file-test/index.html +++ /dev/null @@ -1,289 +0,0 @@ - - - - - - - - - Spec-Up Multi-File Example - - - - - - - - - - - - - - - - - - - - - -
        - - - -
        -

        § Spec-Up Multi-File Example

        -

        Specification Status: Strawman

        -

        Latest Draft: -https://github.com/decentralized-identity/spec-up

        -
        -
        Editors:
        -
        Daniel Buchner
        -
        - -
        -
        Participate:
        -
        GitHub repo
        -
        File a bug
        -
        Commit history
        -
        -
        -

        § Abstract

        -

        Let’s face it, other tools and generators for writing technical specifications aimed at standards bodies or industry groups are cumbersome, underwhelming, and lack the features you might want in a technical specification document. Spec-Up’s goal is to deliver you a better spec-writing experience with far less effort and tedium than other tools in the ecosystem. Spec-Up is a dead simple tool that auto-generates great specs from markdown. The version of markdown Spec-up uses contains all the same features you might expect from common implementations, like GitHub, but adds much more, including notice blocks, complex tables, charts, advanced syntax highlighting, UML diagrams, etc.

        -

        § Getting Started

        -

        Using Spec-Up is easy peasy lemon squeezy:

        -
          -
        1. npm install spec-up
          2. -
        2. Create a subdirectory in your project with two files: -
            -
          • spec.json - add some basic config values, like your desired HTML page title, etc.
            • -
          • spec.md - write the markdown version of your spec here (duh)
            • -
          -
          3. -
        3. In your main node.js file, drop in this bad boy: require('spec-up')()
          4. -
        -

        Boom! That’s it. Spec-Up will auto-detect the location of your spec files and auto-generate your spec’s HTML version every time you hit save after editing your spec.md files. Did I mention you can have multiple specs located at any depth in your project and Spec-Up will crawl up in there and render all those specs like a damn boss? Well it does, because why the hell not.

        -

        Usage

        -

        If your spec.json and package.json and package-lock.json files are in working order, Spec-up can be called from the root of your repo in three different modes:

        - - - - - - - - - - - - - - - - - - - - - -
        commandbehavior
        npm run editafter rendering, this will stay running and the gulp library will watch the source files in your spec directory/ies for changes and re-render any time you save a file. Opening these rendered files in a browser and refreshing them will keep you up to date.
        npm run renderthis renders the site once and does not keep a gulpy watch on the underlying files.
        npm run devthis enables debugging features.
        -

        § Features

        -

        § Diagrams

        -
        -```mermaid
-sequenceDiagram
-  participant Alice
-  participant Bob
-  Alice->>Bob: Hey Bob
-  Bob-->>Alice: Great!
-  Alice->>Bob: How about you?
-  Bob-->>Alice: Doing well!
-```
-
        -
        -sequenceDiagram - participant Alice - participant Bob - Alice->>Bob: Hey Bob - Bob-->>Alice: Great! - Alice->>Bob: How about you? - Bob-->>Alice: Doing well! -
        -

        § Charts

        -
        -```chart
-{
-  "type": "pie",
-  "data": {
-    "labels": [
-      "Red",
-      "Blue",
-      "Yellow"
-    ],
-    "datasets": [
-      {
-        "data": [
-          300,
-          50,
-          100
-        ],
-        "backgroundColor": [
-          "#FF6384",
-          "#36A2EB",
-          "#FFCE56"
-        ],
-        "hoverBackgroundColor": [
-          "#FF6384",
-          "#36A2EB",
-          "#FFCE56"
-        ]
-      }
-    ]
-  }
-}
-```
-
        -{"type":"pie","data":{"labels":["Red","Blue","Yellow"],"datasets":[{"data":[300,50,100],"backgroundColor":["#FF6384","#36A2EB","#FFCE56"],"hoverBackgroundColor":["#FF6384","#36A2EB","#FFCE56"]}]}}

        § Syntax Highlighting

        -
        -```json
-{
-  "@context": "https://www.w3.org/ns/did/v1",
-  "id": "did:example:123456789abcdefghi",
-  "authentication": [{
-    "id": "did:example:123456789abcdefghi#keys-1",
-    "type": "RsaVerificationKey2018",
-    "controller": "did:example:123456789abcdefghi",
-    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
-  }],
-  "service": [{
-    "id":"did:example:123456789abcdefghi#vcs",
-    "type": "VerifiableCredentialService",
-    "serviceEndpoint": "https://example.com/vc/"
-  }]
-}
-```
-
        -
        {
-  "@context": "https://www.w3.org/ns/did/v1",
-  "id": "did:example:123456789abcdefghi",
-  "authentication": [{ 
-    "id": "did:example:123456789abcdefghi#keys-1",
-    "type": "RsaVerificationKey2018",
-    "controller": "did:example:123456789abcdefghi",
-    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
-  }],
-  "service": [{
-    "id":"did:example:123456789abcdefghi#vcs",
-    "type": "VerifiableCredentialService",
-    "serviceEndpoint": "https://example.com/vc/"
-  }]
-}
-
        - -
        - -
        - - - -
        - - - - - ✕ -
        -
          -           - - -
          - Table of Contents - ✕ -
          - -           - -           -
          - undefined -
          - - - - - - \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index 71cf3ea..3997e44 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,45 +1,15 @@ { - "name": "spec-up", - "version": "0.10.7", + "name": "didwebvh", + "version": "1.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "spec-up", - "version": "0.10.7", + "name": "didwebvh", + "version": "1.0.0", "license": "Apache 2.0", "dependencies": { - "@traptitech/markdown-it-katex": "3.3.0", - "axios": "0.21.2", - "find-pkg-dir": "2.0.0", - "fs-extra": "8.1.0", - "gulp": "4.0.2", - "gulp-clean-css": "4.3.0", - "gulp-concat": "2.6.1", - "gulp-terser": "1.2.0", - "jsdom": "^24.0.0", - "markdown-it": "13.0.1", - "markdown-it-anchor": "5.2.5", - "markdown-it-attrs": "4.1.4", - "markdown-it-chart": "^0.2.0", - "markdown-it-container": "^2.0.0", - "markdown-it-deflist": "^2.1.0", - "markdown-it-icons": "^0.4.1", - "markdown-it-ins": "^2.0.0", - "markdown-it-mark": "^2.0.0", - "markdown-it-modify-token": "1.0.2", - "markdown-it-multimd-table": "^4.1.3", - "markdown-it-prism": "^2.2.0", - "markdown-it-references": "1.0.0-alpha.10", - "markdown-it-sub": "^1.0.0", - "markdown-it-sup": "^1.0.0", - "markdown-it-task-lists": "2.1.1", - "markdown-it-textual-uml": "0.1.3", - "markdown-it-toc-and-anchor": "4.2.0", - "merge-stream": "2.0.0", - "pkg-dir": "4.2.0", - "prismjs": ">=1.24.0", - "yargs": "16.2.0" + "spec-up": "github:brianorwhatever/spec-up#master" } }, "node_modules/@traptitech/markdown-it-katex": { @@ -3887,6 +3857,44 @@ "resolved": "https://registry.npmjs.org/spdx-license-ids/-/spdx-license-ids-3.0.11.tgz", "integrity": "sha512-Ctl2BrFiM0X3MANYgj3CkygxhRmr9mi6xhejbdO960nF6EDJApTYpn0BQnDKlnNBULKiCN1n3w9EBkHK8ZWg+g==" }, + "node_modules/spec-up": { + "version": "0.10.8", + "resolved": "git+ssh://git@github.com/brianorwhatever/spec-up.git#fcab95edb4cc8d2a70f8c053e227220dbd6a08de", + "license": "Apache 2.0", + "dependencies": { + "@traptitech/markdown-it-katex": "3.3.0", + "axios": "0.21.2", + "find-pkg-dir": "2.0.0", + "fs-extra": "8.1.0", + "gulp": "4.0.2", + "gulp-clean-css": "4.3.0", + "gulp-concat": "2.6.1", + "gulp-terser": "1.2.0", + "jsdom": "^24.0.0", + "markdown-it": "13.0.1", + "markdown-it-anchor": "5.2.5", + "markdown-it-attrs": "4.1.4", + "markdown-it-chart": "^0.2.0", + "markdown-it-container": "^2.0.0", + "markdown-it-deflist": "^2.1.0", + "markdown-it-icons": "^0.4.1", + "markdown-it-ins": "^2.0.0", + "markdown-it-mark": "^2.0.0", + "markdown-it-modify-token": "1.0.2", + "markdown-it-multimd-table": "^4.1.3", + "markdown-it-prism": "^2.2.0", + "markdown-it-references": "1.0.0-alpha.10", + "markdown-it-sub": "^1.0.0", + "markdown-it-sup": "^1.0.0", + "markdown-it-task-lists": "2.1.1", + "markdown-it-textual-uml": "0.1.3", + "markdown-it-toc-and-anchor": "4.2.0", + "merge-stream": "2.0.0", + "pkg-dir": "4.2.0", + "prismjs": ">=1.24.0", + "yargs": "16.2.0" + } + }, "node_modules/split-string": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/split-string/-/split-string-3.1.0.tgz", diff --git a/package.json b/package.json index eaa0b0a..0bf7664 100644 --- a/package.json +++ b/package.json @@ -1,61 +1,27 @@ { - "name": "spec-up", - "version": "0.10.8", - "description": "Technical specification drafting tool that generates rich specification documents from markdown.", - "main": "./index", - "repository": { - "type": "git", - "url": "git+https://github.com/decentralized-identity/spec-up.git" - }, + "name": "didwebvh", + "version": "1.0.0", + "description": "did:webvh -- did:web + Verifiable History", + "main": "index.js", "scripts": { - "edit": "node -e \"require('./index')()\"", - "render": "node -e \"require('./index')({ nowatch: true })\"", - "dev": "node -e \"require('./index')({ dev: true })\"" + "edit": "node -e \"require('spec-up')()\"", + "render": "node -e \"require('spec-up')({ nowatch: true })\"", + "dev": "node -e \"require('spec-up')({ dev: true })\"" }, "keywords": [ + "decentralized identifier", + "DID", "spec", - "specs", - "markdown", - "editor", - "standards" + "didwebvh", + "tdw" ], - "author": "Daniel Buchner", + "author": "Stephen Curran", "license": "Apache 2.0", "bugs": { - "url": "https://github.com/decentralized-identity/spec-up/issues" + "url": "https://github.com/decentralized-identity/didwebvh/issues" }, - "homepage": "https://github.com/decentralized-identity/spec-up#readme", + "homepage": "https://identity.foundation/didwebvh/", "dependencies": { - "@traptitech/markdown-it-katex": "3.3.0", - "axios": "0.21.2", - "find-pkg-dir": "2.0.0", - "fs-extra": "8.1.0", - "gulp": "4.0.2", - "gulp-clean-css": "4.3.0", - "gulp-concat": "2.6.1", - "gulp-terser": "1.2.0", - "jsdom": "^24.0.0", - "markdown-it": "13.0.1", - "markdown-it-anchor": "5.2.5", - "markdown-it-attrs": "4.1.4", - "markdown-it-chart": "^0.2.0", - "markdown-it-container": "^2.0.0", - "markdown-it-deflist": "^2.1.0", - "markdown-it-icons": "^0.4.1", - "markdown-it-ins": "^2.0.0", - "markdown-it-mark": "^2.0.0", - "markdown-it-modify-token": "1.0.2", - "markdown-it-multimd-table": "^4.1.3", - "markdown-it-prism": "^2.2.0", - "markdown-it-references": "1.0.0-alpha.10", - "markdown-it-sub": "^1.0.0", - "markdown-it-sup": "^1.0.0", - "markdown-it-task-lists": "2.1.1", - "markdown-it-textual-uml": "0.1.3", - "markdown-it-toc-and-anchor": "4.2.0", - "merge-stream": "2.0.0", - "pkg-dir": "4.2.0", - "prismjs": ">=1.24.0", - "yargs": "16.2.0" + "spec-up": "github:brianorwhatever/spec-up#master" } } diff --git a/readme.md b/readme.md deleted file mode 100644 index 1d86e07..0000000 --- a/readme.md +++ /dev/null @@ -1,150 +0,0 @@ - - -

          - - - -

          Markdown » Spec-Up

          - -

          - - - -Spec-Up is a technical specification development tool that enables you to create rich specification documents for standards bodies and engineering projects by writing in an extended version of markdown that features all the bells and whistles - for example: advanced syntax highlighting, notice blocks, complex tables, charts, UML diagrams, and more. - -## Setup - -Installing Spec-Up is easy peasy lemon squeezy: - -0. Node.JS, i.e. `nvm` and its package manager `npm`, are required to run spec-up. WSL2 users should look [here](https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl#install-nvm-nodejs-and-npm) for specific instructions. -1. Run `npm install spec-up` in the root directory of the repo to install all dependencies. -2. Create a `specs.json` file **in the root folder of your repository** to specify configuration values used in the generation of your spec documents. The values in your `specs.json` file include things like where your spec's markdown files are located, where to output the generated spec document, and various metadata values used in rendering, such as the title, logo, and repo links for each of your specs. The following are the required/optional fields supported in the `specs.json` config file: - - - **`public_root`** _(PATH STRING, optional)_ - For some platforms and services where you may want to output your rendered spec, the pathing may differ from the directory structure of your local project. To account for this, you can use the `public_root` property to specify the insertion of a path segment to account for the different in pathing between your local renders and wherever you publish your spec to. - - **`specs`** _(ARRAY, required)_ - the `specs` array contains descriptor objects for each of the specs you are generating in your project, and are composed of the following required and optional properties: - - **`spec_directory`** _(STRING, required)_ - You must specify the **repo-root-relative** location of your spec's markdown file directory. You ****MUST**** name your spec's markdown file `spec.md` and locate it in your `spec_directory` for the tool to automatically find and use it for rendering. If you want to use a different name for the markdown file, or you have multiple markdown files you would like the tool to assemble into one document, you must specify them using the optional`markdown_paths` field described below. See the "multi-file" example in the spec-up repo. - - **`title`** _(STRING, required)_ - You must add a title for your spec, which will be rendered in the generated document's H1 text and page title. - - **`logo`** _(PATH/URI STRING, optional)_ - You may add a reference to a logo asset, either via a path to the asset or a URI - - **`logo_link`** _(URI STRING, optional)_ - The URI you want your logo to point to in the rendered page. - - **`markdown_paths`** _(ARRAY, optional)_ - If you want to name your spec's markdown file something other than `spec.md`, or you have multiple files you would like assembled into a single output document, you must specify their paths as array entries in the order you would like them assembled. The paths in this array are assumed to be based on the `spec_directory` you specified, so _DO NOT_ repeat the full root relative path. - - **`katex`** _(BOOLEAN, optional)_ - To enable TeX support via KaTeX, set this property to `true`. After rendering, be sure to copy the `fonts/` subdirectory, containing the necessary web fonts. - - **`output_path`** _(STRING, optional)_ - If you want the generated spec document to be output to a different location than the `spec_directory` you specified (e.g. the project root for GitHub Pages publishing) you can specify another root relative path (use `./` for root), and the tool will write the document file there instead. - - **`source`** _(OBJECT, optional)_ - this object allows you to configure where repo-specific data is pulled from to power some of the more advanced repo-related features. To do this, specify the code hosting service by adding a service ID string to `host` (currently Spec-Up only supports `"github"`, but this is extensible), add the account/org the repo is located within via the `account` property, and add the repo name under the `repo` property. Here is an example configuration: - - ``` - { - "host": "github", - "account": "decentralized-identity", - "repo": "sidetree" - } - ``` -3. In your main node.js file, or as a package.json script entry, use this invocation call: `require('spec-up')()` - -Boom! That's it. You're ready to start rendering specs as HTML sites locally and/or pushing them to github pages however you see fit to automate. - -## Running the scripts locally - -If your `spec.json` and `package.json` and `package-lock.json` files are in working order and in the root folder of the repo from which it will be deployed, Spec-up can be called by command line (from the root of your repo) in three different modes: - -|command|behavior| -|---|---| -|`npm run edit`|after rendering, this will stay running and the `gulp` library will watch the source files in your spec directory/ies for changes and re-render any time you save a file. Opening these rendered files in a browser and refreshing them will keep you up to date.| -|`npm run render`|this renders the site once and does not keep a gulpy watch on the underlying files.| -|`npm run dev`|this enables debugging features.| - -## Automation - -The above scripts can easily be triggered by github actions. See [this repo's example](https://github.com/decentralized-identity/spec-up/blob/master/.github/workflows/render-specs.yml) - -## Versioning - -The recommended method for hosting multiple historical versions of a given specification at the same URL is simply to duplicate the source file(s) in a subdirectory and to host each version in a fixed subdirectory of the output target (i.e., the GitHub-Pages site). These multiple set-up and output directories can be set by multiple `spec` objects in the `specs` array of the `spec.json` file. For example: - -```json -{ - "specs": [ - { - "title": "Wallet And Credential Interactions", - "spec_directory": "./", - "output_path": "./build", - "logo": "https://rawcdn.githack.com/decentralized-identity/decentralized-identity.github.io/a3ca39717e440302d1fd99a796e7f00e1c42eb2d/images/logo-flat.svg", - "logo_link": "https://identity.foundation", - "source": { - "host": "github", - "account": "decentralized-identity", - "repo": "waci-presentation-exchange" - } - }, - { - "title": "Wallet And Credential Interactions", - "spec_directory": "./v0.1.0", - "output_path": "./build/v0.1.0", - "logo": "https://rawcdn.githack.com/decentralized-identity/decentralized-identity.github.io/a3ca39717e440302d1fd99a796e7f00e1c42eb2d/images/logo-flat.svg", - "logo_link": "https://identity.foundation", - "source": { - "host": "github", - "account": "decentralized-identity", - "repo": "waci-presentation-exchange" - } - } - ] -} -``` -*Note: when copying a version into a subdirectory, relative references, including image links or [[include]] blocks that copy in example files or test vectors, may break; a quick CTRL-F "../" is recommended* - -In the above example, the files in `./v0.1.0` will not be rendered by the build process that searches "./" for markdown files and vice versa-- changing either will not trigger a new build of the other in each PR. - -### Version numbering - -DIF Recommends 3-decimal versions à la SemVer (i.e., v0.1.0 instead of v0.1). - -### Cross-linking across versions - -Links from the currently/nightly/unstable spec to stable/archival versions and vice versa are not automatically generated by the current version of spec-up, so the recommended best practice is to manually add links above the "Editors" section. See: - -
          Examples from Presentation Exchange - -Unstable version: -``` -Presentation Exchange 2.0.0 -================== - -**Specification Status:** Working Group Draft - -**Latest Draft:** - [identity.foundation/presentation-exchange](https://identity.foundation/presentation-exchange) - -**Ratified Versions:** -~ **v1.0.0** - [https://identity.foundation/presentation-exchange/spec/v1.0.0](https://identity.foundation/presentation-exchange/spec/v1.0.0) - -``` - -Stable Version: -``` -Presentation Exchange v1.0.0 -================== - -**Specification Status:** DIF Ratified Specification - -**Latest Draft:** - [identity.foundation/presentation-exchange](https://identity.foundation/presentation-exchange) -``` -
          - -### Archiving stable versions beyond github - -Additionally, some editors may prefer to keep an immutable archive in a system like web.archive.org. For example: - -``` -**Specification Status:** Draft V0.1 (snapshotted and archived on [web.archive.org](https://web.archive.org/web/20211206215823/https://identity.foundation/waci-presentation-exchange/)) -``` - -## Troubleshooting - -- WSL2 users are recommended to use the `bash` option rather than `PowerShell` in the terminal of Visual Studio Code. -- Some users have reported problems using spec-up with node versions 15+; to pin to an older version, simple run: -``` -nvm install 14 -nvm use 14 -npm i npm@6.14.16 -g -``` diff --git a/single-file-test/assets/test.json b/single-file-test/assets/test.json deleted file mode 100644 index be60ea2..0000000 --- a/single-file-test/assets/test.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "foo": { - "bar": 1 - } -} \ No newline at end of file diff --git a/single-file-test/assets/test.text b/single-file-test/assets/test.text deleted file mode 100644 index 10edfcf..0000000 --- a/single-file-test/assets/test.text +++ /dev/null @@ -1 +0,0 @@ -Beam me in, Scotty! \ No newline at end of file diff --git a/single-file-test/spec.md b/single-file-test/spec.md deleted file mode 100644 index 75695d9..0000000 --- a/single-file-test/spec.md +++ /dev/null @@ -1,536 +0,0 @@ -Spec-Up Example -================== - -**Specification Status:** Draft - -**Latest Draft:** - [https://identity.foundation/spec-up](https://identity.foundation/spec-up) - -Editors: -~ [Daniel Buchner](https://www.linkedin.com/in/dbuchner/) - -Participate: -~ [GitHub repo](https://github.com/decentralized-identity/spec-up) -~ [File a bug](https://github.com/decentralized-identity/spec-up/issues) -~ [Commit history](https://github.com/decentralized-identity/spec-up/commits/master) - ------------------------------------- - -## Abstract - -Let's face it, other tools and generators for writing technical specifications aimed at standards bodies or industry groups are cumbersome, underwhelming, and lack the features you might want in a technical specification document. Spec-Up's goal is to deliver you a better spec-writing experience with far less effort and tedium than other tools in the ecosystem. Spec-Up is a simple tool that auto-generates great specs from markdown. The version of markdown Spec-up uses contains all the same features you might expect from common implementations, like GitHub, but adds much more, including notice blocks, complex tables, charts, advanced syntax highlighting, UML diagrams, etc. - -## Getting Started - -Using Spec-Up is easy peasy lemon squeezy: - -1. `npm install spec-up` -2. Create a `specs.json` file **in the root folder of your repository** to specify configuration values used in the generation of your spec documents. The values in your `specs.json` file include things like where your spec's markdown files are located, where to output the generated spec document, and various metadata values used in rendering, such as the title, logo, and repo links for each of your specs. The following are the required/optional fields supported in the `specs.json` config file: - - - **`spec_directory`** _(STRING, required)_ - You must specify the **repo-root-relative** location of your spec's markdown file directory. You ****MUST**** name your spec's markdown file `spec.md` and locate it in your `spec_directory` for the tool to automatically find and use it for rendering. If you want to use a different name for the markdown file, or you have multiple markdown files you would like the tool to assemble into one document, you must specify them using the optional`markdown_paths` field described below. See the "multi-file" example in the spec-up repo. - - **`title`** _(STRING, required)_ - You must add a title for your spec, which will be rendered in the generated document's H1 text and page title. - - **`markdown_paths`** _(ARRAY, optional)_ - If you want to name your spec's markdown file something other than `spec.md`, or you have multiple files you would like assembled into a single output document, you must specify their paths as array entries in the order you would like them assembled. The paths in this array are assumed to be based on the `spec_directory` you specified, so _DO NOT_ repeat the full root relative path. - - **`katex`** _(BOOLEAN, optional)_ - To enable TeX support via KaTeX, set this property to `true`. After rendering, be sure to copy the `fonts/` subdirectory, containing the necessary web fonts. - - **`output_path`** _(STRING, optional)_ - If you want the generated spec document to be output to a different location than the `spec_directory` you specified (e.g. the project root for GitHub Pages publishing) you can specify another root relative path (use `./` for root), and the tool will write the document file there instead. -3. In your main node.js file, drop in this bad boy: `require('spec-up')()` - -Boom! That's it. Spec-Up will auto-detect modifications to files in your `spec_directory` and auto-generate your spec's updated HTML document every time you save a change. - -**Usage** - -If your `spec.json` and `package.json` and `package-lock.json` files are in working order and in the root folder of the repo from which it will be deployed, Spec-up can be called by command line (from the root of your repo) in three different modes: - -|command|behavior| -|---|---| -|`npm run edit`|after rendering, this will stay running and the `gulp` library will watch the source files in your spec directory/ies for changes and re-render any time you save a file. Opening these rendered files in a browser and refreshing them will keep you up to date.| -|`npm run render`|this renders the site once and does not keep a gulpy watch on the underlying files.| -|`npm run dev`|this enables debugging features.| - -## Table of Contents - -<-- You see that beautiful TOC over there to your left? (tap the header link to slide it out on mobile) Yeah, you don't need to do a damn thing, that just magically appears based on your use of `h2`, `h3`, and `h4` headings. - -## Term References - -### Definition Lists - -Many specs may want to include a section for terminology references, and Definition Lists are a great way to do that. Here's how to leverage Spec-Up's automatic term reference features via Definition List markup: - -
          -[[def: Term 1, Term One]]:
-~ This is the first term we will define.
-
-[[def: Term 2, Term Two]]:
-~ This is the second term, but not the last.
-
-[[def: Term 3, Term Three]]:
-~ This is the last term, because you know what they say: third term's the charm!
-
          - -[[def: Term 1, Term One]]: -~ This is the first term we will define. - -[[def: Term 2, Term Two]]: -~ This is the second term, but not the last. - -[[def: Term 3, Term Three]]: -~ This is the last term, because you know what they say: third term's the charm! - -Now let's refer to some of the terms defined above to show how the auto-linking of terms works: [[ref: Term 1]], [[ref: Term Two]], [[ref: Term 3]]. Additionally, as long as you define your terms using Definition Lists (as seen in the markdown above), you will be able to hover any reference to a term to see a tooltip with its definition. - -### Table-defined Terms - -You can also reference table-oriented terms and definitions which are decomposed into heading-titled attributes in distinct cells: - -
          -Variable           | Default Value | Max Value
-------------------- | -------------- | ---------
-[[def: Variable 1]] | 123          | 9999
-
          - -Variable | Default Value | Max Value -------------------- | ------------- | --------- -[[def: Variable 1]] | 123 | 9999 - - -Anytime you add a definition of a term in the first column of a table, like [[ref: Variable 1]], it will link to the cell and display a tooltip with the entire set of row values when you hover the term. - -### External Term References - -It is possible to include references to terms from external spec-up generated specifications. To include a source you would like to pull references from include an `external_specs` array in your spec config. The value should be a key/value object where the key is used in the external reference below and the value is the URL of the external spec. - -::: example -```json -{ - "specs": [ - { - ... - "external_specs": [ - {"PE": "https://identity.foundation/presentation-exchange"} - ] - } - ] -} -``` -::: - -To include an external term reference within your spec use the following format `[[xref: {title}, {term}]]` where `{title}` is the title given to the spec in the config and `{term}` is the term being used. For example using the PE spec given in the example above [[xref: PE, Holder]] - -## Blockquote - -> To be, or not to be, that is the question: -Whether 'tis nobler in the mind to suffer -The slings and arrows of outrageous fortune, -Or to take arms against a sea of troubles -And by opposing end them. To die—to sleep, -No more; - -## Notices - -
          -::: note Basic Note
-  Check this out.
-:::
-
          - -::: note Basic Note - Check this out. -::: - -::: note - Here's another. -::: - -::: note - And one more! -::: - -::: note Basic Note - One last note!!! -::: - -
          -::: issue Issue Notice
-  I take issue with that, kind sir.
-:::
-
          - -::: issue Issue Notice - I take issue with that, kind sir. -::: - -
          -::: warning Warning Notice
-  Houston, I think we have a problem
-:::
-
          - -::: warning Warning Notice - Houston, I think we have a problem -::: - - -
          -::: todo Really Important
-  Get this done!
-:::
-
          - -::: todo Really Important - Get this done! -::: - - -
          -::: example Code Example
-  Put your code block here
-:::
-
          - -::: example Code Example -```json -// Some comment in JSON -{ - "foo": "bar", - "baz": 2 -} -``` -::: - -## Content Insertion - -Use the following format to pull in content from other files in your project: - -
          -This text has been inserted here from another file: [[insert: ./single-file-test/assets/test.text]]
-
          - -This text has been inserted here from another file: [[insert: ./single-file-test/assets/test.text]] - -You can even insert content within more complex blocks, like the JSON object below which is being pulled in and rendered in a syntax-highlighted example block: -
          -::: example Code Example
-```json
-[[insert: ./single-file-test/assets/test.json]]
-```
-:::
-
          - -::: example Code Example -```json -[[insert: ./single-file-test/assets/test.json]] -``` -::: - - -## Tables - -
          -Stage | Direct Products | ATP Yields
-----: | --------------: | ---------:
-Glycolysis | 2 ATP ||
-^^ | 2 NADH | 3--5 ATP |
-Pyruvaye oxidation | 2 NADH | 5 ATP |
-Citric acid cycle | 2 ATP ||
-^^ | 6 NADH | 15 ATP |
-^^ | 2 FADH2 | 3 ATP |
-**30--32** ATP |||
-[Net ATP yields per hexose]
-
          - -Stage | Direct Products | ATP Yields -----: | --------------: | ---------: -Glycolysis | 2 ATP || -^^ | 2 NADH | 3--5 ATP | -Pyruvaye oxidation | 2 NADH | 5 ATP | -Citric acid cycle | 2 ATP || -^^ | 6 NADH | 15 ATP | -^^ | 2 FADH2 | 3 ATP | -**30--32** ATP ||| -[Net ATP yields per hexose] - -
          -|--|--|--|--|--|--|--|--|
-|♜|  |♝|♛|♚|♝|♞|♜|
-|  |♟|♟|♟|  |♟|♟|♟|
-|♟|  |♞|  |  |  |  | |
-|  |♗|  |  |♟|  |  | |
-|  |  |  |  |♙|  |  | |
-|  |  |  |  |  |♘|  | |
-|♙|♙|♙|♙|  |♙|♙|♙|
-|♖|♘|♗|♕|♔|  |  |♖|
-
          - -|--|--|--|--|--|--|--|--| -|♜| |♝|♛|♚|♝|♞|♜ | -| |♟|♟|♟| |♟|♟|♟ | -|♟| |♞| | | | | | -| |♗| | |♟| | | | -| | | | |♙| | | | -| | | | | |♘| | | -|♙|♙|♙|♙| |♙|♙|♙ | -|♖|♘|♗|♕|♔| | |♖ | - -## Sequence Diagrams -
          -```mermaid
-sequenceDiagram
-  Alice ->> Bob: Hello Bob, how are you?
-  Bob-->>John: How about you John?
-  Bob--x Alice: I am good thanks!
-  Bob-x John: I am good thanks!
-  Note right of John: Bob thinks a long
          long time, so long
          that the text does
          not fit on a row.
-
-  Bob-->Alice: Checking with John...
-  Alice->John: Yes... John, how are you?
-```
-
          - -```mermaid -sequenceDiagram - Alice ->> Bob: Hello Bob, how are you? - Bob-->>John: How about you John? - Bob--x Alice: I am good thanks! - Bob-x John: I am good thanks! - Note right of John: Bob thinks a long
          long time, so long
          that the text does
          not fit on a row. - - Bob-->Alice: Checking with John... - Alice->John: Yes... John, how are you? -``` - -## Flows - -
          -```mermaid
-graph TD
-  A[Start] --> B{Is it?}
-  B -->|Yes| C[OK]
-  C --> D[Rethink]
-  D --> B
-  B -->|No| E[End]
-```
-
          - -```mermaid -graph TD - A[Start] --> B{Is it?} - B -->|Yes| C[OK] - C --> D[Rethink] - D --> B - B -->|No| E[End] -``` - -## Charts - -
          -```chart
-{
-  "type": "pie",
-  "data": {
-    "labels": [
-      "Red",
-      "Blue",
-      "Yellow"
-    ],
-    "datasets": [
-      {
-        "data": [
-          300,
-          50,
-          100
-        ],
-        "backgroundColor": [
-          "#FF6384",
-          "#36A2EB",
-          "#FFCE56"
-        ],
-        "hoverBackgroundColor": [
-          "#FF6384",
-          "#36A2EB",
-          "#FFCE56"
-        ]
-      }
-    ]
-  }
-}
-```
-
          - -```chart -{ - "type": "pie", - "data": { - "labels": [ - "Red", - "Blue", - "Yellow" - ], - "datasets": [ - { - "data": [ - 300, - 50, - 100 - ], - "backgroundColor": [ - "#FF6384", - "#36A2EB", - "#FFCE56" - ], - "hoverBackgroundColor": [ - "#FF6384", - "#36A2EB", - "#FFCE56" - ] - } - ] - } -} -``` - -## Syntax Highlighting - -
          -```json
-{
-  "@context": "https://www.w3.org/ns/did/v1",
-  "id": "did:example:123456789abcdefghi",
-  "authentication": [{
-    "id": "did:example:123456789abcdefghi#keys-1",
-    "type": "RsaVerificationKey2018",
-    "controller": "did:example:123456789abcdefghi",
-    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
-  }],
-  "service": [{
-    "id":"did:example:123456789abcdefghi#vcs",
-    "type": "VerifiableCredentialService",
-    "serviceEndpoint": "https://example.com/vc/"
-  }]
-}
-```
-
          - - -```json -{ - "@context": "https://www.w3.org/ns/did/v1", - "id": "did:example:123456789abcdefghi", - "authentication": [{ - "id": "did:example:123456789abcdefghi#keys-1", - "type": "RsaVerificationKey2018", - "controller": "did:example:123456789abcdefghi", - "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n" - }], - "service": [{ - "id":"did:example:123456789abcdefghi#vcs", - "type": "VerifiableCredentialService", - "serviceEndpoint": "https://example.com/vc/" - }] -} -``` - -## TeX Math Equations - -When the `katex` option is enabled, the KaTeX math engine is used for TeX rendering. You can find a list of supported features and examples here: https://katex.org/docs/supported.html. - -$$\begin{pmatrix}x_2 \\ y_2 \end{pmatrix} = -\begin{pmatrix} A & B \\ C & D \end{pmatrix}\cdot -\begin{pmatrix} x_1 \\ y_1 \end{pmatrix}$$ - -$$\def\arraystretch{1.5} - \begin{array}{c:c:c} - a & b & c \\ \hline - d & e & f \\ - \hdashline - g & h & i -\end{array}$$ - -$$ -\underbrace{a+b+c}_{\text{Note: such math, much wow.}} -$$ - -## Tab Panels - - - - -
          - -```json -{ - "foo": "foo", - "baz": 1 -} -``` - -
          -
          - -```json -{ - "foo": "bar", - "baz": 2 -} -``` - -
          -           - -## Fancy Links - -Spec-Up automatically upgrades the links of certain sites, like GitHub. GitHub is the only supported site with Fancy Links right now, but we'll be adding more as we go. - -### GitHub - -- **Issues** - - Source: `https://github.com/decentralized-identity/presentation-exchange/issues/119` - - Render: https://github.com/decentralized-identity/presentation-exchange/issues/119 -- **Pull Requests** - - Source: `https://github.com/decentralized-identity/sidetree/pull/863` - - Render: https://github.com/decentralized-identity/sidetree/pull/863 -- **Releases** - - Source: `https://github.com/decentralized-identity/sidetree/releases/tag/v0.9.1` - - Render: https://github.com/decentralized-identity/sidetree/releases/tag/v0.9.1 -- **Projects** - - Source: `https://github.com/decentralized-identity/sidetree/projects/1` - - Render: https://github.com/decentralized-identity/sidetree/projects/1 - -## External Spec References - -You can reference external specifications from IETF, W3C, and WHATWG as follows: - -1. Anywhere in your document you want to referece an external specification, use the `spec`-prefixed custom token format: `[[spec:RFC4122]]` -2. Wherever in your document you want to print out all your external specification references, use the `spec` custom token format _without any spec name_: `[[spec]]` - - If you want to split up your references into groups (e.g. normative vs informative), just make sure to use dash-delimited unique reference grouping string in your custom tokens: `[[spec-norm:RFC4122]]`, `[[spec-inform:RFC4122]]`, `[[spec-foo:RFC4122]]`, etc. - - To print out a custom group's references, just include the grouping string for a given set of references in a custom token _without any spec name_: `[[spec-norm]]`, `[[spec-inform]]`, `[[spec-foo]]`. - -Here are a set of example references that are distributed among the reference groups `spec`, `spec-norm`, `spec-inform`: - -- [[spec:RFC3548]] (`[[spec:RFC3548]]`) -- [[spec:RFC7518]] (`[[spec:RFC7518]]`) -- [[spec-norm:DID-CORE]] (`[[spec-norm:DID-CORE]]`) -- [[spec-norm:DID-SPEC-REGISTRIES]] (`[[spec-norm:DID-SPEC-REGISTRIES]]`) -- [[spec-inform:RFC6901]] (`[[spec-inform:RFC6901]]`) -- [[spec-inform:RFC7230]] (`[[spec-inform:RFC7230]]`) - -### Default References - -This is what is printed out when you include the `[[spec]]` custom token in your Markdown: - -[[spec]] - - -### Normative References - -This is what is printed out when you include the `[[spec-norm]]` custom token in your Markdown: - -[[spec-norm]] - -### Informative References - -This is what is printed out when you include the `[[spec-inform]]` custom token in your Markdown: - -[[spec-inform]] diff --git a/spec/abstract.md b/spec/abstract.md new file mode 100644 index 0000000..ebdf680 --- /dev/null +++ b/spec/abstract.md @@ -0,0 +1,3 @@ +## Abstract + +This document introduces a standardized `/whois` DID URL path that provides a decentralized mechanism to retrieve a verifiable presentation published by the DID Controller, containing verifiable credentials about the DID and the entity controlling the DID. diff --git a/spec/definitions.md b/spec/definitions.md new file mode 100644 index 0000000..f35a3f2 --- /dev/null +++ b/spec/definitions.md @@ -0,0 +1,14 @@ +## Definitions + +[[def: DID Controller, DID Controllers]] + +~ The DID Controller is the entity that has the authority to update its DID. In + the context of this specification, the DID Controller is the entity + represented by the DID. The `/whois` capability will most often be used + by legal entities that want to establish a Verifiable Credential-backed + linkage between their DID and their legal entity, attested to be a suitable + authority. + +[[def: W3C Verifiable Presentation, Verifiable Presentation]] + +~ A Verifiable Presentation as defined in the W3C [[spec:vcdm]]. diff --git a/spec/header.md b/spec/header.md new file mode 100644 index 0000000..6344b05 --- /dev/null +++ b/spec/header.md @@ -0,0 +1,19 @@ +DID /whois +================== + +**Specification Status:** Draft + +**Latest Draft:** + [https://github.com/decentralized-identity/did-whois](https://github.com/decentralized-identity/did=whois) + +**Editors:** +~ [Stephen Curran](https://github.com/swcurran) +~ [John Jordan](https://github.com/jljordan42) + + +**Participate:** +~ [GitHub repo](https://github.com/decentralized-identity/did-whois) +~ [File a bug](https://github.com/decentralized-identity/did-whois/issues) +~ [Commit history](https://github.com/decentralized-identity/did-whois/commits/main) + +------------------------------------ diff --git a/spec/references.md b/spec/references.md new file mode 100644 index 0000000..8655f1d --- /dev/null +++ b/spec/references.md @@ -0,0 +1,6 @@ +## References + +- [W3C DID Core Specification](https://www.w3.org/TR/did-core/) +- [Linked Data Proofs](https://w3c-ccg.github.io/ld-proofs/) + +[[spec]] diff --git a/spec/security_and_privacy.md b/spec/security_and_privacy.md new file mode 100644 index 0000000..e69de29 diff --git a/spec/specification.md b/spec/specification.md new file mode 100644 index 0000000..7ce9f27 --- /dev/null +++ b/spec/specification.md @@ -0,0 +1,166 @@ +# DID Extension Specification: /whois + +## Introduction + +The `/whois` path introduces a convention for all DID Methods to enable a +resolver to learn more about the public identity of a [[ref: DID Controller]] through the +discovery of Verifiable Credentials about the DID. Inspired by the WHOIS [[spec:rfc3912]] +protocol from the early ARPANET days, this feature allows resolving +`/whois` to retrieve a Verifiable Presentation (VP) containing Verifiable +Credentials containing public information about the [[ref: DID Controller]]. This capability provides: + +- A decentralized mechanism for querying verifiable information about DIDs. +- A trust model based on cryptographic verification of attestations from + (possibly domain specific) authorities rather than centralized registries. + +When `/whois` is resolved using a DID service compliant with the [[spec:linked-vp]], the response is a Verifiable Presentation (VP) +signed by the DID. The VP may contain: + +- Information about the DID and the legal entity of the [[ref: DID Controller]] that the + DID Controller wants to be made public. +- Verifiable Credentials (VCs) with the DID as the `credentialSubject` that may + bind other identifiers (legal name, legal entity registration identifiers, + etc.) to the DID. +- VCs with other identifiers bound (via other VCs in the VP) to the DID as the + `credentialSubject`. + +For example, a VC in the VP may use the DID as the `credentialSubject`, +published by an authority, indicating the DID is associated with a legal entity +with a set of identifiers—such as the legal name of the entity and a +registration identifier (e.g., an LEI as published by [GLEIF]). A second VC in +the VP might use the entity identifier from that first VC as the +`credentialSubject` to include attestations such as ISO certifications. The +resolver decides whether to trust the issuers of the VCs, potentially using +`/whois` with those DIDs to gather information about their identity. + +[GLEIF]: https://www.gleif.org/ + +### /whois Use Case + +#### Example Scenario: Importing a Product Shipment + +Consider the [[ref: DID Controller]] of a mining company exporting a "product" +-- a shipment of the material produced by their mine. The company publishes a +"Digital Product Passport" (DPP) in the form of a Verifiable Credential about +the shipment. An importer resolves the product identifier and retrieves and +verifies the DPP. It wants to know who it was that issued the (self-attested) +DPP verifiable credential. It finds in the DPP the DID of the issuer and then +resolves `/whois`. The mining company has published a VP about its DID, +putting the following verifiable credentials containing public information into +the VP and signing it with its DID: + +1. **A Verifiable Credential attesting to the Legal Entity's Registration:** + + - Details such as the company's legal name, registration date, and contact information might be included. + - The `credentialSubject` of the VC is the same DID that signed the DPP, and the `/whois` VP. + - This enables the importer to identify and verify the legitimacy of the company. + - If necessary, the importer can resolve the `/whois` of the issuer of the VC to learn more about them. + +2. **A Verifiable Credential for a Mining Permit:** + + - Issued by the mining authority (likely a government) in the company's jurisdiction. + - This second VC might use the company’s legal name as the + `credentialSubject` rather than the entity’s DID. The data in the first VC + provides the binding from the legal name to the DID. + - Allows further resolution of the mining permit VC's DID and its `/whois` + path for additional validation. + +3. **A Verifiable Credential for Auditing Practices:** + + - Details about the company's compliance with standards audited by a trusted entity. + - Further resolution of the auditor's DID `/whois` path may verify its accreditation. + +The mining company determines what VCs it wants to publish in its `/whois` VP, +and the importer resolving the DPP can resolve "up the hierarchy" of the various +VCs to find the authorities issuing the collection of VCs. In the end, the +importer software may recognize and trust the authorities issuing the VCs and +make a trust decision on the mining company. If not, the software can take the +collected information (VCs and issuers) and pass that along to a person to make +the trust decision. + +### Decentralized Trust Registry + +The `/whois` path enables: + +- Verification of entities across multiple domains using cryptographic proofs. +- Automated or manual trust decisions based on retrieved information. +- Efficient and decentralized trust establishment comparable to a Certificate Authority hierarchy but self-managed by [[ref: DID Controllers]] and issuers. + +## Implementation Details + +### DID URL Syntax + +The `/whois` path conforms to the following syntax: + +``` +/whois +``` + +### Resolution Process + +1. Resolve the DID and retrieve and verify the DIDDoc. +2. Locate the `#whois` service in the resolved DID Document. This service **MUST** be of type `LinkedVerifiablePresentation`. + 1. A DID Method **MAY** define an implicit `#whois` service that useful for that DID Method. For example, the [[spec:didwebvh]] DID Method has a DID-to-HTTPS-URL transformation used when resolving the DIDDoc, and implicitly defines a `#$whois` service that uses the same DID-to-HTTPS transformation to define the location of the `whois.vp` resource. A [[ref: DID Controller]] **MAY** explicitly include a `#whois` service in their DID Document, overriding the implicit `#whois` service. +3. Resolve the `serviceEndpoint` to obtain the Verifiable Presentation. +4. Verify the VP and the VCs in the VP. +5. Parse the VP to extract Verifiable Credentials and associated metadata. +6. Optionally resolve the `/whois` path of issuers of the VCs for further trust validation as needed and available. + +### Example DID Document Service Item + +The resolved DID Document must include a service item for `/whois` as follows: + +```json +"service": [ + { + "id": "did:example:123#whois", + "type": "LinkedVerifiablePresentation", + "serviceEndpoint": "https://bar.example.com/whois.vp" + } +] +``` + +### Verifiable Presentation Requirements + +- The returned `whois.vp` **MUST** contain a [[ref: W3C Verifiable Presentation]] signed by the DID. +- At least one of the Verifiable Credentials within the VP **MUST** use the DID as the `credentialSubject`. + - Such a VC **MAY** attest to the binding of other identifiers to the DID. For example, the VC may be from an authority that attests to the legal name and registration identifier of the entity controlling the DID. +- The `credentialSubject` of other VCs may be identifiers cryptographically bound in other VCs within the VP to the DID being resolved. + - For example, the legal name or legal entity registration identifier could be the `credentialSubject` if another VC in the VP binds that identifier to the DID. +- The [[ref: DID Controller]] determines which Verifiable Credentials to include based on their usefulness for establishing the identity and trustworthiness of the entity controlling the DID. +- The resolver determines which Verifiable Credentials are useful in its determination of the identity and trustworthiness of the entity controlling the DID. + +What Verifiable Credentials and who should issue those credentials are outside +of the scope of this specification. A future version of the specification may +define at least a credential that binds the DID to the other identifiers used +by/assigned to the legal entity controlling the DID. For example, the +[United Nations Transparency Protocol]'s [Digital Identity Anchor] might be a good +candidate for a standard VC to bind the DID to the legal entity of the +controller. + +[United Nations Transparency Protocol]: https://uncefact.github.io/spec-untp +[Digital Identity Anchor]: https://uncefact.github.io/spec-untp/docs/specification/DigitalIdentityAnchor + +### Error Handling + +Resolvers **MUST** handle errors as follows: + +- If the `serviceEndpoint` cannot be resolved, return `Error 404: Not Found`. +- If the file at the defined `serviceEndpoint` is not found, return `Error 404: Not Found`. +- If the VP fails verification, return `Error 500: Server Error`. + +## Security and Privacy Considerations + +- **Data Minimization:** + - Ensure only necessary public credentials are included in the VP. +- **Cryptographic Integrity:** + - All returned VPs must be signed by the DID Controller. +- **Access Control:** + - There is not an intention to limit access to the `/whois` service endpoint. It is the responsibility of the DID Controller to ensure that only Verifiable Presentations containing public information are published at the service endpoint. + - Personally identifiable information (PII) **MUST NOT** be published to the `/whois` service endpoint. +- **Exposing Sensitive Information:** + - Careful scoping of `/whois` data is necessary to avoid unintentional disclosure. + +## Conclusion + +The `/whois` path standardizes a decentralized mechanism for retrieving verifiable information about DIDs. It empowers trust decisions through cryptographic verification and promotes interoperability across decentralized systems. diff --git a/spec/version.md b/spec/version.md new file mode 100644 index 0000000..e69de29 diff --git a/specs.json b/specs.json index 3a65fae..9f95a92 100644 --- a/specs.json +++ b/specs.json @@ -1,53 +1,58 @@ { "specs": [ { - "title": "Spec-Up Example", - "spec_directory": "./single-file-test", - "output_path": "./", - "logo": "logo.svg", - "logo_link": "https://github.com/decentralized-identity/spec-up", + "title": "DID /whois", + "spec_directory": "./spec", + "markdown_paths": [ + "header.md", + "abstract.md", + "specification.md", + "security_and_privacy.md", + "definitions.md", + "references.md", + "version.md" + ], "source": { "host": "github", "account": "decentralized-identity", - "repo": "spec-up" + "repo": "did-whois" }, + "output_path": "./", + "logo": "https://raw.githubusercontent.com/decentralized-identity/did-whois/refs/heads/main/logo.jpg", + "logo_link": "https://github.com/decentralized-identity/did-whois", + "katex": true, "external_specs": [ { - "PE": "https://identity.foundation/presentation-exchange" - } - ], - "assets": [ - { - "path": "/custom-assets/custom.css" - }, - { - "path": "/custom-assets/custom-head.js", - "inject": "head" + "linked-vp": { + "href": "https://identity.foundation/linked-vp/spec/v1.0.0/", + "title": "Linked Verifiable Presentation v1.0.0", + "rawDate": "2024-07-03", + "authors": [ + "Jan Christoph Ebersbach", + "Brian Richter", + "Markus Sabadello" + ], + "status": "DIF Ratified Specification" + } }, { - "path": "/custom-assets/custom-body.js", - "inject": "body", - "module": true + "didwebvh": { + "href": "https://identity.foundation/didwebvh/", + "title": "did:webvh DID Method", + "rawDate": "2024-12-20", + "authors": [ + "Stephen Curran", + "John Jordan", + "Brian Richter", + "Andrew Whitehead", + "Michel Sahli", + "Martina Kolpondinos", + "Dmitri Zagdulin" + ], + "status": "Draft" + } } - ], - "katex": true - }, - { - "title": "Spec-Up Multi-File Example", - "spec_directory": "./multi-file-test", - "markdown_paths": [ - "header.md", - "abstract.md", - "getting-started.md", - "features.md" - ], - "logo": "../logo.svg", - "logo_link": "https://github.com/decentralized-identity/spec-up", - "source": { - "host": "github", - "account": "decentralized-identity", - "repo": "spec-up" - } + ] } ] } \ No newline at end of file diff --git a/specup_logo.png b/specup_logo.png deleted file mode 100644 index 1235583b0586e1b2e110f01f1c68fcde868cf09a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3194 zcma);hf~wr632f@s38I>O%$X>ItB$Pf(8gmsG$X=`1FTF=zDp- z_etGcJxXY^4dXO{&GZD6?I_Qp8lRx;v$z(Ft2k+^TMwio=@4F8F<*m7+tqrpy!Y!* zw9Thz+IuSPo0uEhCdjdf*2HS|oN!|3k$;2~Q^Hzpe*F9R$1?FYcdFw&h0+TDH1X@? zZ)vq1!dr>aERsfccqGd0YAv`*DWsY*qwtANH7)?Ure_t_F{-I_X{;A7HxZ3<^2__K z;K|F>CK12xAQU-rl@RCAh{~)PA#wrS{R0j9Do0eJv@;pr{<`F$sEljzQI`I?oQUr5 zv3=0>_wnLgZ=ueFVd#8fulOiKqcLsB{KNuKWqv!J=*E%H&odOgJeh z&9WP@&FZHUZ*u!P%(H{;i`jp-0Ii9kb4C`i+ZV|749H5drVFxR0O}38E%AH z9&9ajMLBRjz)=-%^tJ|;xCDfEP;%WT#Le|DWj^a@0v}QOU*IXQH&^QX>A=stjv-^G zcD2$41cN5|A_5?op%2M#dG+H&D^LU_#&x{PZ7cDxyWBA5GU;D}y0RDE#oubu_y2XA zT_W(pLl4XMz3><6cb4Eq4I>8!Xm;R+p%3bpwEB80saSRWiTo~AcD)R=NLOFg{{alX zz86rteQzC~D%2YO=ggy}Z3_XR%snaeNamhAdgSTec9N;H2ol-l=!UNwCRAu{p2mY! zkawhL)fTu=o0^LX?Kd9d6JG>MlatXnDn%!)20@(>&V4g2gDJ`0OM1}FeoWDME>@d< zn9sBJ;1l;fq=Ua#1+Qhy8?3*q{D5}&hn3<%9{JsuvgS_#P1MqxEo#zjswCS5y={{< zmGE=NMASZL5!07#Y!7(fj+>y?X83chNs($aY6*I4SFg)E30EuQ-#9T1{Bjy&qjWN7 z;G3szdz^jrbGVTZHR{)7<#6lpCcwV2s-)zwT5;X*MVK1Ov{-Lc0RF%Sb;3hoy+D36 zhg8pxcfltM+6o|F{uARm8h>SPF&2$`*o4)RE0}tU6%ww_==5e9SAfVb%-PwLJ_X@J zA(Ds8`YQi!zUp5zP}l99lW2G=wdwZ9Q4lUpLCn0Q&8nPd@pql;t#YY5Fh_`1{dbIO zJk!YHlg|Mky2%2E<*|)b;^!UkJhxnQanK)h-PO9P!(~IVVf?bo-i5I2S4 z;Dq><`hy3(*qeR#VS`aK5$dJp_`8C0K$82I_iMiZlO(Cn3(nmdURgZMXuoM3qkj=n z+ck2k+8mGg_VO1+kg8(<7A?s!byg8v2YD(J)ODQWo59%N0(IlCtk;~khGHcyEPqA7 z4uD5O7{l=L9zDhS4Z@r8qSay2r40QssoiLc=cfmxQtK|DvjEMu#m6=SJ3B|hiZVy| zqr6QC%Hz*O@E%i9vvejWtL%fA0O?v(idL z&sfvZ_~YyOas{#GIMaKU2Br_G-w?=8nj3aWHq?{47drgR*kzQy-ZQy~&)e{Jm(eGR zF*mz5CyRfX|71JmFj0@(CfBCxF*M8Iu zvwKh|G$j`dsh1OD=*~{PG^#hC_&9(J3RSAqL-Iva%JhR*228U`>t)@D5oE_AMxY+P zTic;3@rgOkwI_?6OKB3v{8j-CG#vMKk48{@h}~x+1rQG~qpbpKF+P9o$fCDT6uj%- za|Cx!zw^9`jhS3-V1zp#ld8_@6ndL+Le(CQTuX$1^kv*MuYy?Wp7y7UWXPU0Y5E&% zqL&mNmf#Ok+0;lt_+8Hx*C;4?W;AISHmO=+PGdZ;8;WqmHUOHB8Q_;e18Svj<9)k8 zws97xboN&j3@Kcp=du<~lRR`7W@H!qtz_l4P@kECvBEIiF1>=Q@&~T1`Qlis5pDj$WO;6<%4dNFI7@TD}TD&u+hCH-(GF> zQtfMlfMf11USrAvRUO6T#R*8ll?M0Vp0*Tqljg!BPgwH{_q*&M!S5htmwm;^{CK8P zAJ5p(bV*!_EOwwXqID=rI`7<=hld{V!7^L+XBh9%NxoI+Fwh;7l9U@Acxxt!wqB&y z{Q03#>%!LxO)UsUIF@#C$nHWUYtYgzyQ(AyG+h}G2H5sU&dyX?*)m!QFs3n3mOrbB z*QWWJ^;z>IY1+3mH#Io$+%f_ZX?0(C|8iI)CQhsX#bJ$`6UTdXkOEvODob8~!lm-~ zOvd?~R82@d2G5?jxgeTuE;U_yrJGw3&I7rD|6L7Cu7Qu2yoPR6mAlAtJl{>ZlTGN6 zO-pA1PO zULHFs@`A5J)3jXW2VY8O(UcW#tE4JU6iX>J0?5XLgL&V zuATS4d)5uxgUefLUvjU~GgjUfU`-B-^@}M*d5$#vI|IOjX=*2?!D*SItHwkNH5ju$ zDNiY?0jM>~jCXFfKHtkK5g;EM;fvy%WD0AXTDbY)Xs&a6iTu1J-H;K#iRzc}Pg1LF zKvv$98QOOtxrygXkYVkHCfUQl_+*lf^3K8=R^j#!Z!5mDr~2S_$;WIeaD0>V!a)^F zU_1Ju;TP>zq)GC?eq=CFi=wujZml_YlFSVruRa$&xR!Y+;L!H@p{qdRg!e_E8QhPH zSLtVcKKl&Z!HWqp9~SYFyUrSV?GqNa5eAIWoqNRS576H}EiK#rvX*q15*f zNd22Hh6#gKJz_s|aCs^JZAAD|R9QAXD%_D@Xu%+%Ael&bQ74@k-G=Hj>R99H2Sj-> z>N_9P0(BxocjmP^cQYG({faP+$VOxjvO5Su^v=8#@J%=n-zmv94A@;R_cOr5;8}aV9<26Pl7yu<)6E5 zvMa_v0d#-CPZ%@d+ZD~C+Fo5w)e|3s-B&nN!l|j|xyE#y2m&eKAK;|j4(3s6fBrty z2r5D5)^4oK_W(gMJ?vNMG8|@!lbmt1s>XxNtEpjb>0r*Zq;1lkJ9Pr(ljC|CW*|sC zxi`{rOf~%!`8>SH($jkN7I&)sJPdu%m&rnkXKvzGH^(u$yz z6a@)rj)lIy$h$dL0*?sYa#a23zOEn=rSKLrpPlEnJ#+%s$e}HJmCnJ5>uk0y(1IGR z$|!F&8lA`pl^TYQS9I=^UZtx2C;V4jDCt#3n(pomR$jS`xACi zP~uU~sW#ZY?rA*Vfth}5_jI!*mW<)v$_hsS;pGZReu5m(>{jkXZ1)1fXu9tT#?7U# z4*VB(-kE-aCM3LsT+#loBmfI^fWF12Gejbq^w~v?@K%9hA(ru?z4kWKWo3T0uk4}yt}sYcMiM^ ZfAiiEYgg