Skip to content

Commit 8489f21

Browse files
coodoscoodos
authored
Docs/ontology and registry (#749)
* docs: add links, ontology and registry * chore: add cross references * chore: fix metadata * chore: fix links * feat: add link to docs at readme * chore: fix favicon * chore: fix code rabbit suggestions
1 parent dbd6652 commit 8489f21

24 files changed

Lines changed: 497 additions & 144 deletions

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# MetaState Prototype
22

3+
**[Documentation](https://docs.w3ds.metastate.foundation)** — Getting started with W3DS and the MetaState prototype.
4+
35
## Docker Development Environment
46

57
### Port Assignments

‎docs/docs/Getting Started/_category_.json‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,4 @@
11
{
22
"label": "Getting Started",
3-
"position": 1,
4-
"link": {
5-
"type": "generated-index"
6-
}
3+
"position": 1
74
}

‎docs/docs/Getting Started/getting-started.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -88,25 +88,25 @@ graph TB
8888

8989
### eVault Core
9090

91-
The **eVault Core** is the central storage system that manages user data. It provides:
91+
The [eVault Core](/docs/Infrastructure/eVault) is the central storage system that manages user data. It provides:
9292

9393
- **GraphQL API** for storing and retrieving data using MetaEnvelope storage for structured data
9494
- **Webhook delivery** to notify platforms of data changes
9595
- **Access control** via ACLs (Access Control Lists)
9696

9797
### Web3 Adapter
9898

99-
The **Web3 Adapter** is a library that platforms use to:
99+
The [Web3 Adapter](/docs/Infrastructure/Web3-Adapter) is a library that platforms use to:
100100

101101
- Handle bidirectional data synchronization between local databases and eVaults
102102
- Convert between platform-specific schemas and global ontology schemas
103103

104104
### Registry Service
105105

106-
The **Registry Service** provides:
106+
The [Registry Service](/docs/Infrastructure/Registry) provides:
107107

108108
- **W3ID resolution**: Maps eNames (like `@user-a.w3id`) to eVault URLs
109-
- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication)
109+
- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication). See [eVault — Key Binding Certificates](/docs/Infrastructure/eVault#key-binding-certificates) and [Registry](/docs/Infrastructure/Registry).
110110
- **Platform registration**: Tracks active platforms for webhook delivery
111111

112112
### Platforms
@@ -130,7 +130,7 @@ User Action → Platform Database → Web3 Adapter → User's eVault → Webhook
130130
1. **User Action**: User creates a post, message, or other data
131131
2. **Platform Database**: Platform stores data locally
132132
3. **Web3 Adapter**: Adapter converts data to global schema and syncs to eVault
133-
4. **User's eVault**: eVault stores the data as a MetaEnvelope
133+
4. **User's eVault**: eVault stores the data as a [MetaEnvelope](/docs/Infrastructure/eVault#data-model)
134134
5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one)
135135
6. **All Platforms**: Other platforms receive webhooks and create the data locally
136136

@@ -169,7 +169,7 @@ sequenceDiagram
169169

170170
### Registration Sequence
171171

172-
The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the Provisioner and Registry services:
172+
The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the [Provisioner](/docs/W3DS%20Basics/Links) (production URL) and [Registry](/docs/Infrastructure/Registry) services:
173173

174174
```mermaid
175175
sequenceDiagram
@@ -195,6 +195,8 @@ sequenceDiagram
195195
Wallet-->>User: Onboarding complete
196196
```
197197

198+
The [Provisioner](/docs/W3DS%20Basics/Links) hosts `/provision`; the [Registry](/docs/Infrastructure/Registry) resolves eNames and issues key binding certificates; [eVault Core](/docs/Infrastructure/eVault) stores user data.
199+
198200
## Next Steps
199201

200202
- Learn more about [W3DS Basics](/docs/W3DS%20Basics/getting-started) - Deep dive into eVault ownership and data flow

‎docs/docs/Infrastructure/Ontology.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
sidebar_position: 5
3+
---
4+
5+
# Ontology
6+
7+
The Ontology service is the schema registry for W3DS. It serves JSON Schema (draft-07) definitions identified by a W3ID (`schemaId`). eVault uses these schema IDs in MetaEnvelopes to indicate the type of stored data and to map envelope fields to schema property names.
8+
9+
## Overview
10+
11+
- **Schema registry**: Schemas define the shape of data stored in eVault (posts, users, messages, votes, etc.).
12+
- **Schema IDs**: Each schema has a unique `schemaId` (W3ID). eVault’s MetaEnvelope `ontology` field stores this W3ID; each Envelope’s `ontology` field stores the **property name** from the schema (e.g. `content`, `authorId`, `createdAt`).
13+
- **API**: List schemas and fetch a schema by W3ID as raw JSON. A human-facing viewer is also available at the service root.
14+
15+
See [eVault — Data Model](/docs/Infrastructure/eVault#data-model) for how MetaEnvelopes and Envelopes use ontology.
16+
17+
## API
18+
19+
### GET /schemas
20+
21+
Returns a list of all available schemas.
22+
23+
**Response** (200):
24+
25+
```json
26+
[
27+
{ "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User" },
28+
{ "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost" }
29+
]
30+
```
31+
32+
- `id`: Schema W3ID (`schemaId`).
33+
- `title`: Human-readable schema title.
34+
35+
### GET /schemas/:id
36+
37+
Returns the full JSON Schema for the given W3ID. Use this when you need the complete schema definition (e.g. for validation or to know required fields and types).
38+
39+
**Path parameter**: `id` — the schema’s `schemaId` (W3ID, e.g. `550e8400-e29b-41d4-a716-446655440001`).
40+
41+
**Response** (200): JSON Schema object (draft-07) with `schemaId`, `title`, `type`, `properties`, `required`, `additionalProperties`, etc.
42+
43+
**Errors**:
44+
45+
- **404**: Schema not found for the given W3ID.
46+
47+
### Human-facing viewer
48+
49+
- **GET /** — Renders a viewer page that lists schemas and supports search. Optional query `?q=...` filters by title or ID; `?schema=<id>` shows one schema.
50+
- **GET /schema/:id** — Same viewer with a specific schema selected (permalink).
51+
52+
These endpoints are for browsing in a browser; for integration use `GET /schemas` and `GET /schemas/:id`.
53+
54+
## Schema format
55+
56+
Each schema file is JSON Schema draft-07 and must include:
57+
58+
- **schemaId**: W3ID that uniquely identifies the schema (used in eVault MetaEnvelopes).
59+
- **title**: Short name (e.g. `SocialMediaPost`, `User`).
60+
- **type**: Typically `"object"`.
61+
- **properties**: Map of property names to JSON Schema types (string, number, array, object, etc.). In eVault, each property becomes an Envelope whose `ontology` field is this property name.
62+
- **required**: Array of required property names.
63+
- **additionalProperties**: Usually `false` for strict typing.
64+
65+
Example (conceptually):
66+
67+
```json
68+
{
69+
"$schema": "http://json-schema.org/draft-07/schema#",
70+
"schemaId": "550e8400-e29b-41d4-a716-446655440001",
71+
"title": "SocialMediaPost",
72+
"type": "object",
73+
"properties": {
74+
"id": { "type": "string", "format": "uri", "description": "W3ID" },
75+
"authorId": { "type": "string", "format": "uri", "description": "W3ID" },
76+
"content": { "type": "string" },
77+
"createdAt": { "type": "string", "format": "date-time" }
78+
},
79+
"required": ["id", "authorId", "createdAt"],
80+
"additionalProperties": false
81+
}
82+
```
83+
84+
In eVault, a MetaEnvelope for a post would have `ontology: "550e8400-e29b-41d4-a716-446655440001"`, and its Envelopes would have `ontology` values such as `content`, `authorId`, `createdAt`.
85+
86+
## Available schemas
87+
88+
To see all available schemas, call `GET /schemas` on the [Ontology production service](/docs/W3DS%20Basics/Links) or browse the [viewer](https://ontology.w3ds.metastate.foundation/) at the production base URL.
89+
90+
## Integration
91+
92+
- **eVault**: Stores `schemaId` in MetaEnvelope `ontology` and property names in Envelope `ontology`. Platforms and clients use the Ontology service to resolve schema W3IDs to full schemas for validation and display. See [eVault](/docs/Infrastructure/eVault).
93+
- **Platforms**: Use schema IDs when calling eVault (e.g. `storeMetaEnvelope`, `findMetaEnvelopesByOntology`) and fetch schemas from the Ontology service when they need field definitions or validation. See [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) and [Mapping Rules](/docs/Post%20Platform%20Guide/mapping-rules).
94+
95+
## References
96+
97+
- [eVault](/docs/Infrastructure/eVault) — MetaEnvelopes, Envelopes, and the `ontology` field
98+
- [W3DS Basics](/docs/W3DS%20Basics/getting-started) — Ontology and schema concepts
99+
- [Links](/docs/W3DS%20Basics/Links) — Production Ontology base URL

‎docs/docs/Infrastructure/Registry.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
sidebar_position: 4
3+
---
4+
5+
# Registry
6+
7+
The Registry is a core W3DS service that provides W3ID-based service discovery, entropy generation for cryptographic operations, and—as a temporary shortcut—key binding certificates. In the future, key binding will be provided by a Remote Notary (Remote CA).
8+
9+
## Overview
10+
11+
The Registry enables clients and services to:
12+
13+
- **Resolve W3IDs** to service endpoints (eVault URIs, platform URLs)
14+
- **Obtain entropy** as signed JWTs for use in provisioning and other operations
15+
- **Verify tokens** via a public JWK endpoint
16+
17+
:::warning Remote Notary / Remote CA
18+
19+
**Key binding certificates** are intended to be provided by a **Remote Notary** (Remote CA) in the future. The Registry currently provides them as a **shortcut** for the prototype. This function will be performed by a remote CA later; treat the Registry’s current behavior as temporary.
20+
21+
:::
22+
23+
## Architecture
24+
25+
```mermaid
26+
graph TB
27+
subgraph Clients["Clients"]
28+
EVault[eVault Core]
29+
Platform[Platforms]
30+
Wallet[eID Wallet]
31+
end
32+
33+
subgraph Registry["Registry"]
34+
Resolve[GET /resolve]
35+
List[GET /list]
36+
Entropy[GET /entropy]
37+
JWKS["GET /.well-known/jwks.json"]
38+
end
39+
40+
subgraph RegistryAuth["Registry (temporary)"]
41+
KeyBinding[Key binding certificates]
42+
end
43+
44+
subgraph Storage["Storage"]
45+
DB[(Vault entries)]
46+
end
47+
48+
EVault -->|Resolve W3ID| Resolve
49+
EVault -->|List platforms| List
50+
Platform -->|Resolve / list| Resolve
51+
Wallet -->|Entropy for provisioning| Entropy
52+
Resolve --> DB
53+
List --> DB
54+
KeyBinding --> JWKS
55+
```
56+
57+
## Service discovery
58+
59+
### GET /resolve?w3id=\<w3id\>
60+
61+
Resolves a W3ID to the associated service details (eVault or platform endpoint).
62+
63+
**Query parameter**: `w3id` (required) — the W3ID to resolve (e.g. `@user.w3id` or a service identifier).
64+
65+
**Response** (200):
66+
67+
```json
68+
{
69+
"ename": "@user.w3id",
70+
"uri": "https://resolved-service.example.com",
71+
"evault": "evault-identifier",
72+
"originalUri": "https://...",
73+
"resolved": false
74+
}
75+
```
76+
77+
- **404**: No vault entry found for the given W3ID.
78+
- **400**: Missing `w3id` parameter.
79+
80+
eVault and platforms use this to find where a user’s eVault or a platform’s API is hosted. See [eVault](/docs/Infrastructure/eVault) for how resolution is used in access control and webhook delivery.
81+
82+
### GET /list
83+
84+
Returns all registered vault entries (ename, uri, evault) with URIs resolved (e.g. for health checks or discovery). No authentication required.
85+
86+
**Response** (200): Array of objects with `ename`, `uri`, `evault`, `originalUri`, `resolved`.
87+
88+
## Entropy
89+
90+
### GET /entropy
91+
92+
Returns a signed JWT containing 20 alphanumeric characters of cryptographically secure entropy. Used by the eID Wallet and provisioning flows (e.g. when creating a new eVault).
93+
94+
**Response** (200):
95+
96+
```json
97+
{
98+
"token": "eyJhbGciOiJFUzI1NiIs..."
99+
}
100+
```
101+
102+
**Token payload** (inside the JWT):
103+
104+
- `entropy`: 20-character alphanumeric string
105+
- `iat`, `exp`: Issued at and expiration (valid for 1 hour)
106+
107+
**Signing**: ES256. Verify using the public key from `GET /.well-known/jwks.json`.
108+
109+
## JWK discovery
110+
111+
### GET /.well-known/jwks.json
112+
113+
Returns the JSON Web Key Set (JWK) used to sign entropy tokens and key binding certificates. Clients use this to verify JWTs issued by the Registry.
114+
115+
**Response** (200): Standard JWK set (e.g. EC P-256, ES256, `use: "sig"`).
116+
117+
## Key binding certificates (temporary)
118+
119+
The Registry can issue **key binding certificates**: JWTs that bind a W3ID (eName) to a public key. eVault uses these when storing and serving public keys (e.g. via `/whois`). Platforms verify signatures using the public key from the certificate and validate the certificate using the Registry’s JWKS.
120+
121+
**Flow**:
122+
123+
1. eVault (or provisioning) stores a user’s public key and requests a key binding certificate from the Registry (internal/protected flow).
124+
2. The certificate is stored and later served (e.g. in eVault’s `/whois` response).
125+
3. Platforms fetch certificates and verify them with the Registry’s public key.
126+
127+
**Certificate payload** (inside the JWT): `ename`, `publicKey`, `iat`, `exp` (e.g. 1 hour).
128+
129+
:::warning
130+
131+
Key binding attestation will be performed by a **Remote CA** in the future. The Registry currently issues these certificates as a shortcut.
132+
133+
:::
134+
135+
See [eVault — Key Binding Certificates](/docs/Infrastructure/eVault#key-binding-certificates) for how eVault uses them.
136+
137+
## Data model (high level)
138+
139+
The Registry stores **vault entries** used for resolution. Each entry conceptually has:
140+
141+
- **ename**: W3ID (e.g. `@user.w3id` or service identifier)
142+
- **uri**: Service endpoint URL (resolved at runtime, e.g. with health checks)
143+
- **evault**: eVault identifier for routing
144+
145+
Entropy and key binding tokens are JWTs signed with ES256; structure is described in the sections above. Registration and management of vault entries are internal and not documented as part of the public API.
146+
147+
## Integration
148+
149+
- **eVault**: Calls Registry to resolve W3IDs (access control, webhook targets), and uses key binding certificates for `/whois`. See [eVault](/docs/Infrastructure/eVault) and [Authentication](/docs/W3DS%20Protocol/Authentication).
150+
- **[eID Wallet](/docs/Infrastructure/eID-Wallet)**: Uses `/entropy` during provisioning. Verifies JWTs using `/.well-known/jwks.json`.
151+
- **Platforms**: Use `/resolve` and `/list` for discovery; see [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started). Verify tokens with the Registry’s JWKS.
152+
153+
## References
154+
155+
- [eVault](/docs/Infrastructure/eVault) — Resolution, key binding, and webhook delivery
156+
- [eID Wallet](/docs/Infrastructure/eID-Wallet) — Provisioning and entropy
157+
- [W3ID](/docs/W3DS%20Basics/W3ID) — Identifiers and eName resolution
158+
- [Links](/docs/W3DS%20Basics/Links) — Production Registry URL
159+
- [Authentication](/docs/W3DS%20Protocol/Authentication) — How platforms authenticate users
160+
- [Signing](/docs/W3DS%20Protocol/Signing) — Signature verification using eVault keys

0 commit comments

Comments
 (0)