docs: add infrastructure, protocol, and getting started docs #721
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. 📝 WalkthroughWalkthroughThis PR adds and restructures extensive W3DS documentation: new protocol specifications for Authentication and Signing, new infrastructure pages for eVault and eID-Wallet, and reworks Getting Started guides toward conceptual and architectural content (diagrams, data flows, webhook lifecycle, and payload examples). Changes
Sequence Diagram(s)sequenceDiagram
participant Platform
participant User as eID Wallet
participant EVault
participant Registry
participant Validator
Platform->>Platform: generate login offer (session UUID, w3ds://auth URI)
Platform-->>User: return offer / display QR or deep link
User->>EVault: sign session (private key) & send signed payload to redirect URL
Platform->>Registry: resolve w3id / fetch public key(s)
Platform->>EVault: (optional) fetch meta-envelope or certificate for verification
Platform->>Validator: verify signature against public key / certificate
Validator-->>Platform: verification result (ok / fail)
Platform-->>User: issue auth token / complete login
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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: 6
🤖 Fix all issues with AI agents
In `@docs/docs/Infrastructure/eID-Wallet.md`:
- Around line 182-189: The fenced code block containing the message sequence
starting with "Wallet → Registry: GET /entropy" is missing a Markdown language
tag; update the opening triple-backtick fence to include a language such as text
(or http) so markdownlint stops flagging it (e.g., change ``` to ```text) and
ensure the rest of the block remains unchanged.
- Around line 95-98: Current doc text contradicts itself between the "Real
KYC/Verification" and "Hardware Available" bullets; update the wording so "Real
KYC/Verification" is explicitly hardware-only with no software fallback except
for the limited pre-verification/test-user case, and change the "Hardware
Available" bullet to state it applies only to non-KYC/test flows (e.g., "For
non-KYC flows: prefer hardware, fall back to software for test/pre-verification
users"). Ensure both bullets reference the same exception scope
(pre-verification/test users) and remove any phrasing that implies a general
fallback for Real KYC/Verification.
- Around line 383-386: The auth payload uses the property ename (ename:
vault.ename) but the protocol and signing workflow expect w3id; change the
payload property from ename to w3id (e.g., replace ename: vault.ename with w3id:
<vault identifier>) so the payload field matches the signing workflow and server
lookups, and update any code that constructs or consumes this payload (including
places that read sessionId, signature, and appVersion) to use w3id consistently
so public key retrieval in the signing workflow works correctly.
In `@docs/docs/Infrastructure/eVault.md`:
- Around line 367-384: The env docs block is missing required DB and
verification variables; update the code block that lists environment variables
to include PostgreSQL connection URLs (e.g., PROVISIONER_DATABASE_URL and
REGISTRY_DATABASE_URL), Veriff integration keys (PUBLIC_VERIFF_KEY and
VERIFF_HMAC_KEY), PUBLIC_EVAULT_SERVER_URI, optional DB_CA_CERT for SSL, and the
demo code variable (DEMO_CODE_W3DS) so the documented envs match the deployment
requirements and architecture diagram.
In `@docs/docs/W3DS` Protocol/Authentication.md:
- Around line 258-263: The example calls isVersionValid(appVersion, "0.4.0") but
never defines it; add a clear implementation or example in the docs that shows
how to compare semantic versions (e.g., parse appVersion and minVersion into
major/minor/patch numbers and compare them lexicographically) and reference the
function name isVersionValid, the parameters appVersion and minVersion, and the
expected boolean return so implementers can copy or adapt it directly.
In `@docs/docs/W3DS` Protocol/Signing.md:
- Around line 326-330: Change the phrase that currently reads "Certificates
expire 1 hour after issuance." to use a hyphenated form "Certificates have
1-hour validity." (or "Certificates expire after 1-hour validity.") — update the
sentence in the section that mentions the `exp` claim and the `publicKey`
extraction under "JWT Payload Structure" so the documentation uses the
hyphenated "1-hour validity".
🧹 Nitpick comments (8)
docs/docs/Infrastructure/eVault.md (2)
88-90: Add language identifier to fenced code block.The fenced code block showing the Neo4j storage structure should specify a language identifier for proper syntax highlighting and better readability.
📝 Suggested fix
-``` +```cypher (MetaEnvelope {id, ontology, acl}) -[:LINKS_TO]-> (Envelope {id, value, valueType})</details> --- `294-299`: **Document the rationale for the 3-second webhook delay.** The 3-second delay to prevent "webhook ping-pong" is mentioned but not fully explained. Consider adding more context: - What exactly is webhook ping-pong? - Why is 3 seconds the chosen duration? - Are there edge cases where this delay might cause issues? This would help implementers understand the design decision and potential trade-offs. </blockquote></details> <details> <summary>docs/docs/W3DS Basics/getting-started.md (2)</summary><blockquote> `280-283`: **Add language identifier to fenced code block.** The fenced code block showing W3ID resolution should specify a language identifier for proper rendering. <details> <summary>📝 Suggested fix</summary> ```diff -``` +```http GET /resolve?w3id=@user-a.w3id → Returns: https://evault.example.com/users/user-a</details> --- `148-165`: **Consider adding webhook retry/failure handling guidance.** The webhook payload documentation is clear, but it doesn't address what happens if webhook delivery fails. Based on eVault.md, webhooks are fire-and-forget with no retries, but this could lead to data inconsistency across platforms. Consider adding a note about: - What happens when webhook delivery fails - How platforms can detect missing updates - Whether platforms should implement a polling mechanism as backup - Handling eventual consistency </blockquote></details> <details> <summary>docs/docs/W3DS Protocol/Authentication.md (2)</summary><blockquote> `65-67`: **Add language identifier to fenced code block.** The w3ds://auth URI example should specify a language identifier for proper rendering. <details> <summary>📝 Suggested fix</summary> ```diff - ``` + ```text w3ds://auth?redirect={redirectUrl}&session={sessionId}&platform={platformName} ```
163-163: Clarify the appVersion sunset timeline.The documentation mentions that
appVersionis temporary and will be sunset "after the rollout is completed," but there's no indication of when that might be or what the rollout refers to. This could cause confusion for platform implementers.Consider adding:
- An approximate timeline or milestone for when this field will be removed
- What "rollout" refers to (e.g., "eID wallet version 1.0 adoption")
- Whether platforms should plan to handle both the presence and absence of this field
docs/docs/Getting Started/getting-started.md (2)
127-129: Add language identifier to fenced code block.The data flow diagram should specify a language identifier for proper rendering.
📝 Suggested fix
-``` +```text User Action → Platform Database → Web3 Adapter → User's eVault → Webhooks → All Platforms</details> --- `140-144`: **Consider clarifying the relationship between the two "Getting Started" docs.** There are now two "getting-started.md" files in different directories: - `docs/docs/Getting Started/getting-started.md` (this file) - `docs/docs/W3DS Basics/getting-started.md` While this file provides a high-level overview and the W3DS Basics version provides deeper technical detail, new users might be confused about which to read first. Consider: 1. Adding a note at the top of each file explaining their relationship 2. Renaming one to better differentiate (e.g., "Overview" vs "Deep Dive") 3. Adding cross-references between the two </blockquote></details> </blockquote></details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
coodos
force-pushed
the
docs/getting-started-and-w3ds-basics
branch
from
502ffa2 to
0d6bb33
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/docs/Infrastructure/eID-Wallet.md`:
- Around line 397-402: Update the "Hardware keys not available" section to
remove the incorrect fallback claim and state that the eID Wallet enforces a
hardware key manager during onboarding with no fallback to software keys;
specifically, replace the bullet that reads "If hardware is unavailable, the
wallet will fallback to software keys" with a clear statement that onboarding
cannot proceed without hardware keys and ensure the note about KYC-verified
users always using hardware keys (referenced around line 96) remains consistent.
♻️ Duplicate comments (4)
docs/docs/Infrastructure/eID-Wallet.md (2)
182-189: Add language tag to code fence.The code fence is missing a language specifier.
✍️ Proposed fix
-``` +```text Wallet → Registry: GET /entropy Registry → Wallet: JWT entropy token Wallet → Provisioner: POST /provision (entropy, namespace, publicKey) Provisioner → Registry: Request key binding certificate Registry → Provisioner: JWT certificate Provisioner → Wallet: w3id, evaultUri ```
95-98: Clarify hardware key enforcement without fallback.Lines 96 and 97-98 contradict each other. Line 96 correctly states that real KYC/verification always uses hardware keys with no software fallback, but line 97-98 suggests a fallback exists. This contradicts the actual implementation.
✍️ Suggested fix
1. **Pre-verification Mode**: Always uses software keys (for testing/fake users only) 2. **Real KYC/Verification**: Always uses hardware keys (never software keys) -3. **Hardware Available**: Prefers hardware keys, falls back to software only if hardware is unavailable +3. **Hardware Pre-test**: The wallet performs a pre-test during onboarding to verify hardware key availability. If hardware keys are unavailable, onboarding cannot proceed for real users. 4. **Explicit Request**: Can force hardware or software based on configurationBased on learnings, in the eID Wallet, hardware key manager is always enforced on onboarding flows. The wallet performs a pre-test to check if hardware keys are available, and there is no fallback to software keys for real users.
docs/docs/Infrastructure/eVault.md (1)
364-391: Add missing PostgreSQL environment variables.The deployment requirements (line 361) explicitly state "PostgreSQL: For verification and notification storage," but the environment variables section does not document any PostgreSQL connection strings (e.g.,
PROVISIONER_DATABASE_URL,REGISTRY_DATABASE_URL). This creates a gap between stated requirements and configuration guidance.Based on learnings, the project uses Digital Ocean managed PostgreSQL which requires specific SSL configuration for database connections.
docs/docs/W3DS Protocol/Authentication.md (1)
258-263: Provide implementation forisVersionValidfunction.The example code calls
isVersionValid(appVersion, "0.4.0")but this function is never defined or explained. Platform implementers may not know how to implement version validation correctly.💡 Suggested implementation example
Add a note or code example explaining version validation:
// Helper function for semantic version comparison function isVersionValid(appVersion: string, minVersion: string): boolean { if (!appVersion) return false; const [major, minor, patch] = appVersion.split('.').map(Number); const [minMajor, minMinor, minPatch] = minVersion.split('.').map(Number); if (major > minMajor) return true; if (major < minMajor) return false; if (minor > minMinor) return true; if (minor < minMinor) return false; return patch >= minPatch; }
🧹 Nitpick comments (4)
docs/docs/Infrastructure/eVault.md (1)
86-88: Add language tag to code fence.The code fence is missing a language specifier, reducing readability.
✍️ Proposed fix
-``` +```text (MetaEnvelope {id, ontology, acl}) -[:LINKS_TO]-> (Envelope {id, value, valueType})</details> </blockquote></details> <details> <summary>docs/docs/W3DS Protocol/Signing.md (3)</summary><blockquote> `67-69`: **Add language tag to code fence.** The code fence displaying the URI format is missing a language specifier. <details> <summary>✍️ Proposed fix</summary> ```diff - ``` + ```text w3ds://sign?session={sessionId}&data={base64Data}&redirect_uri={encodedRedirectUri} ```
272-274: Add language tag to code fence.The code fence is missing a language specifier for the HTTP request example.
✍️ Proposed fix
-``` +```http GET {registryBaseUrl}/resolve?w3id=@user-a.w3id</details> --- `290-294`: **Add language tag to code fence.** The code fence is missing a language specifier for the HTTP request example. <details> <summary>✍️ Proposed fix</summary> ```diff -``` +```http GET {evaultUrl}/whois Headers: X-ENAME: `@user-a.w3id`</details> </blockquote></details> </blockquote></details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| ## Core Concept | ||
|
|
||
| ### What you'll need | ||
| The fundamental principle of W3DS is simple: **Users, groups, and objects own their own eVaults**. All data about a person, group, or object is stored in their eVault, and platforms become frontends that display and interact with this data. |
There was a problem hiding this comment.
not just frontends, but also acting as cache and aggregators
|
|
||
| - [Node.js](https://nodejs.org/en/download/) version 20.0 or above: | ||
| - When installing Node.js, you are recommended to check all checkboxes related to dependencies. | ||
| ### Key Principles |
There was a problem hiding this comment.
we want to emphasisze that 2+3 == interoperability
and 1 and 4 is quite similar and related
| 2. Blabsy's Web3 Adapter syncs the post to User A's eVault | ||
| 3. User A's eVault stores the post and notifies all registered platforms | ||
| 4. **Pictique** (another social media platform) receives the notification | ||
| 5. Pictique creates the post locally - User A now has a post on Pictique **without ever visiting Pictique** |
There was a problem hiding this comment.
this formulation will sound spooky to a lot of people out there
| The **eVault Core** is the central storage system that manages user data. It provides: | ||
|
|
||
| ## Start your site | ||
| - **GraphQL API** for storing and retrieving data |
There was a problem hiding this comment.
again, it feels that the first and the last should be united
|
|
||
| - Sync local database changes to eVaults | ||
| - Convert between platform-specific schemas and global ontology schemas | ||
| - Handle bidirectional data synchronization |
There was a problem hiding this comment.
if it is bidirectional why did we bother to say sync local db to vault above?
|
|
||
| ### Resolution | ||
|
|
||
| W3IDs are resolved to eVault URLs via the Registry Service: |
There was a problem hiding this comment.
I thought Alex wanted the registry to sign this, because again, spoofing and holding them accountable for resolution of enames? Did we convince him not to do it in the prototype?
|
|
||
| ### Resolution | ||
|
|
||
| W3IDs are resolved to eVault URLs via the Registry Service: |
There was a problem hiding this comment.
I thought Alex wanted the registry to sign this, because again, spoofing and holding them accountable for resolution of enames? Did we convince him not to do it in the prototype?
|
|
||
| The user's eID wallet signs the session ID using their private key. The signing process: | ||
|
|
||
| 1. **Parse the w3ds://auth URI**: Extract the `session` parameter from the query string. The session ID is a UUID string that must be signed exactly as received. |
There was a problem hiding this comment.
should mention the QR vs. deeplink flows distinctions
|
|
||
| - Session IDs must be **cryptographically random** (use UUID v4) | ||
| - Each session ID should be used **only once** | ||
| - Expire session IDs after a reasonable time (e.g., 5 minutes) |
There was a problem hiding this comment.
there should be an explanation why -- because if you don't this bad thing may happen
|
|
||
| - **Never expose sensitive information** in error messages | ||
| - Log verification failures for security monitoring | ||
| - Return generic errors to prevent information leakage |
| ## Generate a new site | ||
| 1. **Data Ownership**: Users own their data, not platforms | ||
| 2. **Platform Independence**: Platforms are interchangeable frontends | ||
| 3. **Automatic Synchronization**: Data created on one platform automatically appears on all platforms |
There was a problem hiding this comment.
add recommendation on message delivery queue implementation to account for evault/platform downtime
| subgraph EVaults["eVaults"] | ||
| EVaultA[User A's eVault] | ||
| EVaultB[User B's eVault] | ||
| EVaultG1[Group 1's eVault] | ||
| end |
There was a problem hiding this comment.
rename parent block to evault provider maybe?
| Blabsy -->|Resolve eName| Registry | ||
| Pictique -->|Resolve eName| Registry |
There was a problem hiding this comment.
if we are not implying that other platforms will not be able to use registry service, maybe consider showing a dashed line reference
| 2. **Platform Database**: Platform stores data locally | ||
| 3. **Web3 Adapter**: Adapter converts data to global schema and syncs to eVault | ||
| 4. **User's eVault**: eVault stores the data as a MetaEnvelope | ||
| 5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one) |
There was a problem hiding this comment.
also might be worth having a sequence diagram of interactions between the layers inclusive of web 3 adapter internal implementation
registration sequence diagram might also help to understand the role of the provisioner and registry better for theoretical knowledge required to setup a w3ds environment locally
| - **Key Management**: Generate and manage ECDSA P-256 key pairs | ||
| - **Hardware Security**: Uses device cryptographic enclaves (Secure Enclave on iOS, Hardware Security Module on Android) |
There was a problem hiding this comment.
atm these but it's all dependent on what we decide to support in the plugin, maybe link it over here to give context?
| subgraph KeyManagers["Key Managers"] | ||
| Hardware[HW Key Manager<br/>Secure Enclave/HSM] | ||
| Software[SW Key Manager<br/>Web Crypto API] | ||
| end |
There was a problem hiding this comment.
should have determination layer above as we sort of logically autodetect the hardware support depending on the
- environment the app is being used in (preverification code based/kyc based)
- device hardware module support
| ### Generate Key | ||
|
|
||
| Generate a new ECDSA P-256 key pair: | ||
|
|
||
| **Process**: | ||
| 1. Determine key manager (hardware or software) | ||
| 2. Generate key pair using appropriate API | ||
| 3. Store key identifier (not the private key itself) | ||
| 4. Return public key | ||
|
|
||
| **Implementation**: | ||
| - Hardware: Uses device-native key generation | ||
| - Software: Uses `crypto.subtle.generateKey()` with ECDSA P-256 parameters | ||
|
|
There was a problem hiding this comment.
maybe have an explicit mention to the plugin lib implementation to avoid shadow/implied knowledge on these limitations
| subgraph Client["Clients"] | ||
| Platform[Platforms] | ||
| Wallet[eID Wallet] | ||
| end | ||
| subgraph EVaultCore["eVault Core"] | ||
| GraphQL[GraphQL Server<br/>/graphql] | ||
| HTTP[HTTP Server<br/>/whois] | ||
| Webhook[Webhook Delivery] | ||
| AccessGuard[Access Guard<br/>ACL Enforcement] | ||
| end |
There was a problem hiding this comment.
this shows platforms interacting directly with evaults without having the web3adapter abstraction layer
| #### 1. User Creates Post on Blabsy | ||
|
|
||
| User A opens Blabsy and creates a post with the text "Hello, world!". Blabsy stores this in its local PostgreSQL database. |
There was a problem hiding this comment.
someone might waste time looking into postgres implementation on blabsy when it uses firebase, consider using pictique as an example here instead or change it to firebase
| sequenceDiagram | ||
| participant User as User (eID Wallet) | ||
| participant Platform as Platform API | ||
| participant Registry as Registry Service | ||
| participant EVault as User's eVault | ||
| participant Validator as Signature Validator | ||
| User->>Platform: 1. Request login | ||
| Platform->>Platform: 2. Generate session ID | ||
| Platform-->>User: 3. Return w3ds://auth URI<br/>(contains session ID) | ||
| User->>User: 4. Sign session ID<br/>with private key | ||
| User->>Platform: 5. POST to redirect URL<br/>(w3id, session, signature, appVersion) | ||
| Platform->>Validator: 6. verifySignature() | ||
| Validator->>Registry: 7. GET /resolve?w3id=@user.w3id | ||
| Registry-->>Validator: 8. eVault URL | ||
| Validator->>EVault: 9. GET /whois<br/>(X-ENAME: @user.w3id) | ||
| EVault-->>Validator: 10. keyBindingCertificates[] | ||
| Validator->>Registry: 11. GET /.well-known/jwks.json | ||
| Registry-->>Validator: 12. JWKS | ||
| Validator->>Validator: 13. Verify JWT with JWKS | ||
| Validator->>Validator: 14. Extract public key from JWT | ||
| Validator->>Validator: 15. Verify signature<br/>(ECDSA P-256, SHA-256) | ||
| Validator-->>Platform: 16. Verification result | ||
| alt Signature Valid | ||
| Platform->>Platform: 17. Create user session | ||
| Platform-->>User: 18. Authentication token | ||
| else Signature Invalid | ||
| Platform-->>User: 19. Authentication failed | ||
| end |
There was a problem hiding this comment.
add session id refresh/invalidation on 60 seconds without authentication note and reasoning for practice in existing platforms
Description of change
Add documentation around
Issue Number
Type of change
How the change has been tested
Local
Change checklist
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.