Docs/ontology and registry

README.md

@@ -1,5 +1,7 @@
 # MetaState Prototype
 
+**[Documentation](https://docs.w3ds.metastate.foundation)** — Getting started with W3DS and the MetaState prototype.
+
 ## Docker Development Environment
 
 ### Port Assignments

docs/docs/Getting Started/_category_.json

@@ -1,7 +1,4 @@
 {
     "label": "Getting Started",
-    "position": 1,
-    "link": {
-        "type": "generated-index"
-    }
+    "position": 1
 }

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

@@ -88,25 +88,25 @@ graph TB
 
 ### eVault Core
 
-The **eVault Core** is the central storage system that manages user data. It provides:
+The [eVault Core](/docs/Infrastructure/eVault) is the central storage system that manages user data. It provides:
 
 - **GraphQL API** for storing and retrieving data using MetaEnvelope storage for structured data
 - **Webhook delivery** to notify platforms of data changes
 - **Access control** via ACLs (Access Control Lists)
 
 ### Web3 Adapter
 
-The **Web3 Adapter** is a library that platforms use to:
+The [Web3 Adapter](/docs/Infrastructure/Web3-Adapter) is a library that platforms use to:
 
 - Handle bidirectional data synchronization between local databases and eVaults
 - Convert between platform-specific schemas and global ontology schemas
 
 ### Registry Service
 
-The **Registry Service** provides:
+The [Registry Service](/docs/Infrastructure/Registry) provides:
 
 - **W3ID resolution**: Maps eNames (like `@user-a.w3id`) to eVault URLs
-- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication)
+- **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).
 - **Platform registration**: Tracks active platforms for webhook delivery
 
 ### Platforms
@@ -130,7 +130,7 @@ User Action → Platform Database → Web3 Adapter → User's eVault → Webhook
 1. **User Action**: User creates a post, message, or other data
 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
+4. **User's eVault**: eVault stores the data as a [MetaEnvelope](/docs/Infrastructure/eVault#data-model)
 5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one)
 6. **All Platforms**: Other platforms receive webhooks and create the data locally
 
@@ -169,7 +169,7 @@ sequenceDiagram
 
 ### Registration Sequence
 
-The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the Provisioner and Registry services:
+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:
 
 ```mermaid
 sequenceDiagram
@@ -195,6 +195,8 @@ sequenceDiagram
     Wallet-->>User: Onboarding complete
 ```
 
+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.
+
 ## Next Steps
 
 - Learn more about [W3DS Basics](/docs/W3DS%20Basics/getting-started) - Deep dive into eVault ownership and data flow

docs/docs/Infrastructure/Ontology.md

@@ -0,0 +1,99 @@
+---
+sidebar_position: 5
+---
+
+# Ontology
+
+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.
+
+## Overview
+
+- **Schema registry**: Schemas define the shape of data stored in eVault (posts, users, messages, votes, etc.).
+- **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`).
+- **API**: List schemas and fetch a schema by W3ID as raw JSON. A human-facing viewer is also available at the service root.
+
+See [eVault — Data Model](/docs/Infrastructure/eVault#data-model) for how MetaEnvelopes and Envelopes use ontology.
+
+## API
+
+### GET /schemas
+
+Returns a list of all available schemas.
+
+**Response** (200):
+
+```json
+[
+    { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User" },
+    { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost" }
+]
+```
+
+- `id`: Schema W3ID (`schemaId`).
+- `title`: Human-readable schema title.
+
+### GET /schemas/:id
+
+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).
+
+**Path parameter**: `id` — the schema’s `schemaId` (W3ID, e.g. `550e8400-e29b-41d4-a716-446655440001`).
+
+**Response** (200): JSON Schema object (draft-07) with `schemaId`, `title`, `type`, `properties`, `required`, `additionalProperties`, etc.
+
+**Errors**:
+
+- **404**: Schema not found for the given W3ID.
+
+### Human-facing viewer
+
+- **GET /** — Renders a viewer page that lists schemas and supports search. Optional query `?q=...` filters by title or ID; `?schema=<id>` shows one schema.
+- **GET /schema/:id** — Same viewer with a specific schema selected (permalink).
+
+These endpoints are for browsing in a browser; for integration use `GET /schemas` and `GET /schemas/:id`.
+
+## Schema format
+
+Each schema file is JSON Schema draft-07 and must include:
+
+- **schemaId**: W3ID that uniquely identifies the schema (used in eVault MetaEnvelopes).
+- **title**: Short name (e.g. `SocialMediaPost`, `User`).
+- **type**: Typically `"object"`.
+- **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.
+- **required**: Array of required property names.
+- **additionalProperties**: Usually `false` for strict typing.
+
+Example (conceptually):
+
+```json
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "schemaId": "550e8400-e29b-41d4-a716-446655440001",
+    "title": "SocialMediaPost",
+    "type": "object",
+    "properties": {
+        "id": { "type": "string", "format": "uri", "description": "W3ID" },
+        "authorId": { "type": "string", "format": "uri", "description": "W3ID" },
+        "content": { "type": "string" },
+        "createdAt": { "type": "string", "format": "date-time" }
+    },
+    "required": ["id", "authorId", "createdAt"],
+    "additionalProperties": false
+}
+```
+
+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`.
+
+## Available schemas
+
+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.
+
+## Integration
+
+- **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).
+- **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).
+
+## References
+
+- [eVault](/docs/Infrastructure/eVault) — MetaEnvelopes, Envelopes, and the `ontology` field
+- [W3DS Basics](/docs/W3DS%20Basics/getting-started) — Ontology and schema concepts
+- [Links](/docs/W3DS%20Basics/Links) — Production Ontology base URL

docs/docs/Infrastructure/Registry.md

@@ -0,0 +1,160 @@
+---
+sidebar_position: 4
+---
+
+# Registry
+
+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).
+
+## Overview
+
+The Registry enables clients and services to:
+
+- **Resolve W3IDs** to service endpoints (eVault URIs, platform URLs)
+- **Obtain entropy** as signed JWTs for use in provisioning and other operations
+- **Verify tokens** via a public JWK endpoint
+
+:::warning Remote Notary / Remote CA
+
+**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.
+
+:::
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph Clients["Clients"]
+        EVault[eVault Core]
+        Platform[Platforms]
+        Wallet[eID Wallet]
+    end
+
+    subgraph Registry["Registry"]
+        Resolve[GET /resolve]
+        List[GET /list]
+        Entropy[GET /entropy]
+        JWKS["GET /.well-known/jwks.json"]
+    end
+
+    subgraph RegistryAuth["Registry (temporary)"]
+        KeyBinding[Key binding certificates]
+    end
+
+    subgraph Storage["Storage"]
+        DB[(Vault entries)]
+    end
+
+    EVault -->|Resolve W3ID| Resolve
+    EVault -->|List platforms| List
+    Platform -->|Resolve / list| Resolve
+    Wallet -->|Entropy for provisioning| Entropy
+    Resolve --> DB
+    List --> DB
+    KeyBinding --> JWKS
+```
+
+## Service discovery
+
+### GET /resolve?w3id=\<w3id\>
+
+Resolves a W3ID to the associated service details (eVault or platform endpoint).
+
+**Query parameter**: `w3id` (required) — the W3ID to resolve (e.g. `@user.w3id` or a service identifier).
+
+**Response** (200):
+
+```json
+{
+    "ename": "@user.w3id",
+    "uri": "https://resolved-service.example.com",
+    "evault": "evault-identifier",
+    "originalUri": "https://...",
+    "resolved": false
+}
+```
+
+- **404**: No vault entry found for the given W3ID.
+- **400**: Missing `w3id` parameter.
+
+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.
+
+### GET /list
+
+Returns all registered vault entries (ename, uri, evault) with URIs resolved (e.g. for health checks or discovery). No authentication required.
+
+**Response** (200): Array of objects with `ename`, `uri`, `evault`, `originalUri`, `resolved`.
+
+## Entropy
+
+### GET /entropy
+
+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).
+
+**Response** (200):
+
+```json
+{
+    "token": "eyJhbGciOiJFUzI1NiIs..."
+}
+```
+
+**Token payload** (inside the JWT):
+
+- `entropy`: 20-character alphanumeric string
+- `iat`, `exp`: Issued at and expiration (valid for 1 hour)
+
+**Signing**: ES256. Verify using the public key from `GET /.well-known/jwks.json`.
+
+## JWK discovery
+
+### GET /.well-known/jwks.json
+
+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.
+
+**Response** (200): Standard JWK set (e.g. EC P-256, ES256, `use: "sig"`).
+
+## Key binding certificates (temporary)
+
+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.
+
+**Flow**:
+
+1. eVault (or provisioning) stores a user’s public key and requests a key binding certificate from the Registry (internal/protected flow).
+2. The certificate is stored and later served (e.g. in eVault’s `/whois` response).
+3. Platforms fetch certificates and verify them with the Registry’s public key.
+
+**Certificate payload** (inside the JWT): `ename`, `publicKey`, `iat`, `exp` (e.g. 1 hour).
+
+:::warning
+
+Key binding attestation will be performed by a **Remote CA** in the future. The Registry currently issues these certificates as a shortcut.
+
+:::
+
+See [eVault — Key Binding Certificates](/docs/Infrastructure/eVault#key-binding-certificates) for how eVault uses them.
+
+## Data model (high level)
+
+The Registry stores **vault entries** used for resolution. Each entry conceptually has:
+
+- **ename**: W3ID (e.g. `@user.w3id` or service identifier)
+- **uri**: Service endpoint URL (resolved at runtime, e.g. with health checks)
+- **evault**: eVault identifier for routing
+
+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.
+
+## Integration
+
+- **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).
+- **[eID Wallet](/docs/Infrastructure/eID-Wallet)**: Uses `/entropy` during provisioning. Verifies JWTs using `/.well-known/jwks.json`.
+- **Platforms**: Use `/resolve` and `/list` for discovery; see [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started). Verify tokens with the Registry’s JWKS.
+
+## References
+
+- [eVault](/docs/Infrastructure/eVault) — Resolution, key binding, and webhook delivery
+- [eID Wallet](/docs/Infrastructure/eID-Wallet) — Provisioning and entropy
+- [W3ID](/docs/W3DS%20Basics/W3ID) — Identifiers and eName resolution
+- [Links](/docs/W3DS%20Basics/Links) — Production Registry URL
+- [Authentication](/docs/W3DS%20Protocol/Authentication) — How platforms authenticate users
+- [Signing](/docs/W3DS%20Protocol/Signing) — Signature verification using eVault keys