docs: add docs for key delegation and auth #720
Conversation
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughAdds new and updated documentation for Infrastructure and W3DS Protocol (including an eVault key delegation guide and a signatures spec), adjusts several docs category ordering files, and enables Mermaid diagram support in the Docusaurus config and docs package dependencies. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@docs/docs/W3DS` Protocol/Signatures.md:
- Around line 24-26: Add a fenced-code language identifier (e.g., text or
plaintext) to the signature code blocks in Signatures.md so they satisfy
markdownlint MD040 and render correctly; locate the triple-backtick blocks
containing the signature lines like "Signature:
\"MEUCIQDxK3vJZQ2F3k5L8mN9pQrS7tUvW1xY3zA5bC7dE9fG1h==\"" and the other similar
blocks (around the other mentioned signature blocks) and change ``` to ```text
for each occurrence (including the blocks referenced at the other ranges).
- Around line 59-64: Update the multibase prefix usages so they match the actual
encodings: replace any occurrence that pairs the 'z' prefix with hex payloads to
use the 'f' prefix for base16/hex (lowercase), change examples that show
z{base64-encoded-SPKI} to use the 'm' prefix for base64 (no padding), and
correct any statements that say "base58btc, but using base64 here" to choose the
intended encoding and apply its correct prefix (use 'z' for base58btc, 'm' for
base64, 'f' for base16). Ensure all examples and descriptive lines consistently
use the correct prefix for their shown payloads (e.g., hex → 'f', base64 → 'm',
base58btc → 'z') so the Signatures.md multibase examples and descriptions are
accurate.
- Around line 17-32: Replace the DER-encoded example signature with a true P1363
raw signature example: update the "Example: Signature" value so it is a base64
encoding of a 64-byte raw ECDSA P-256 signature (32-byte r followed by 32-byte
s), and ensure the surrounding text refers to "P1363 (raw 64-byte r||s) base64"
and to the signing call crypto.subtle.sign() producing that raw format; locate
the current example string near the Example block and swap it for a base64
string that decodes to 64 bytes (r||s).
In `@docs/package.json`:
- Around line 18-21: The `@docusaurus/theme-mermaid` entry currently uses a caret
range ("@docusaurus/theme-mermaid": "^3.9.2") which allows minor-version drift;
change it to the exact version string matching the other Docusaurus packages
("@docusaurus/theme-mermaid": "3.9.2") so all `@docusaurus/`* packages are pinned
to the same version, then reinstall/update lockfile (npm/yarn/pnpm) to commit
the deterministic dependency change.
🧹 Nitpick comments (1)
docs/docs/Infrastructure/eVault-Key-Delegation.md (1)
109-121: Call out the publicKey encoding in the endpoint section.Earlier you mention multibase encoding in the diagram, but the endpoint request doesn’t specify it. Consider adding a one‑liner (e.g., “publicKey is multibase‑encoded”) to avoid ambiguity.
|
|
||
| When provisioning an eVault during onboarding, the eID wallet: | ||
| 1. Generates or retrieves the public key using `getApplicationPublicKey()` | ||
| 2. Includes the `publicKey` in the provision request |
There was a problem hiding this comment.
should cross reference docs explaining /provision endpoint
|
|
||
| ### Key Binding Certificates | ||
|
|
||
| Key binding certificates are JWTs that cryptographically bind a public key to an eName. They are generated by the Registry service and stored in eVault. |
There was a problem hiding this comment.
should mark that they are generated in the Registry only in the prototype and that it was mostly arbitrary decision
| - **Payload**: `{ ename: "@user.w3id", publicKey: "z..." }` | ||
| - **Signature**: Signed by Registry's private key (ES256) | ||
|
|
||
| The certificate is valid for 1 hour and can be verified using the Registry's JWKS endpoint at `/.well-known/jwks.json`. |
There was a problem hiding this comment.
should reference documentation about registry's endpoints. This one I particularly dislike btw.
| - **Payload**: `{ ename: "@user.w3id", publicKey: "z..." }` | ||
| - **Signature**: Signed by Registry's private key (ES256) | ||
|
|
||
| The certificate is valid for 1 hour and can be verified using the Registry's JWKS endpoint at `/.well-known/jwks.json`. |
There was a problem hiding this comment.
should explain the purpose of this JWT -- it is to allow anyone to validate signatures by the private key of the public key presented here. And one hour is quite arbitrary
|
|
||
| #### PATCH /public-key | ||
|
|
||
| Stores a public key in eVault for a given eName. |
There was a problem hiding this comment.
who can run this? does this override the old public key? how does this work with the option for multiple keys described below?
|
|
||
| 1. **Key Storage**: Private keys are never transmitted or stored in eVault. Only public keys are synced. | ||
|
|
||
| 2. **Certificate Validity**: Key binding certificates expire after 1 hour. eVault regenerates them on-demand when requested. |
There was a problem hiding this comment.
what is the attack vector or confusion we are trying to avoid here?
|
@nsergey82 I will address your comments later, for now we will just merge to unblock geosemantica |
|
|
||
| ### Verification Steps | ||
|
|
||
| 1. **Resolve eVault URL**: Query Registry with eName to get eVault URI |
There was a problem hiding this comment.
which endpoint? and how does one know the url of the registry?
| ### Verification Steps | ||
|
|
||
| 1. **Resolve eVault URL**: Query Registry with eName to get eVault URI | ||
| 2. **Get Key Binding Certificates**: Request `/whois` endpoint from eVault |
There was a problem hiding this comment.
maybe using URI from [1] for clarity
| 3. **Verify JWT**: Verify each certificate's signature using Registry JWKS | ||
| 4. **Extract Public Key**: Get public key from JWT payload | ||
| 5. **Decode Public Key**: Convert multibase format to bytes | ||
| 6. **Import Public Key**: Import into Web Crypto API |
There was a problem hiding this comment.
import for example into Web Crypto API
|
|
||
| 2. **Payload Validation**: Always verify that the signed payload matches the expected content before processing. | ||
|
|
||
| 3. **Certificate Expiration**: Key binding certificates expire after 1 hour. Ensure your verification logic handles expired certificates gracefully. |
| **Algorithm Steps:** | ||
|
|
||
| 1. **Request Entropy** | ||
| - Send GET request to Registry `/entropy` endpoint |
There was a problem hiding this comment.
I hope we could remove this feature
Description of change
add docs for key delegation and auth
Issue Number
Type of change
How the change has been tested
Change checklist
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.