diff --git a/README.md b/README.md index 0c4912ec..59f53c6f 100644 --- a/README.md +++ b/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 diff --git a/docs/docs/Getting Started/_category_.json b/docs/docs/Getting Started/_category_.json index b3543aa7..f2c55c6f 100644 --- a/docs/docs/Getting Started/_category_.json +++ b/docs/docs/Getting Started/_category_.json @@ -1,7 +1,4 @@ { "label": "Getting Started", - "position": 1, - "link": { - "type": "generated-index" - } + "position": 1 } diff --git a/docs/docs/Getting Started/getting-started.md b/docs/docs/Getting Started/getting-started.md index e52a7284..b206ec65 100644 --- a/docs/docs/Getting Started/getting-started.md +++ b/docs/docs/Getting Started/getting-started.md @@ -88,7 +88,7 @@ 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 @@ -96,17 +96,17 @@ The **eVault Core** is the central storage system that manages user data. It pro ### 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 diff --git a/docs/docs/Infrastructure/Ontology.md b/docs/docs/Infrastructure/Ontology.md new file mode 100644 index 00000000..f35a0a06 --- /dev/null +++ b/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=` 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 diff --git a/docs/docs/Infrastructure/Registry.md b/docs/docs/Infrastructure/Registry.md new file mode 100644 index 00000000..a9a8d348 --- /dev/null +++ b/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=\ + +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 diff --git a/docs/docs/Infrastructure/Web3-Adapter.md b/docs/docs/Infrastructure/Web3-Adapter.md index 9bf87be8..145e86c7 100644 --- a/docs/docs/Infrastructure/Web3-Adapter.md +++ b/docs/docs/Infrastructure/Web3-Adapter.md @@ -13,7 +13,7 @@ automatically sync with eVaults, if your application is stateless or the applica Platforms keep their own schemas and databases. To participate in W3DS, they need a component that: -- **Outbound**: Detects local changes, maps local data to the global ontology, resolves the owner's and/or target eVault (via the user's [eName](/docs/W3DS%20Basics/W3ID) / Registry), and writes to the eVault (GraphQL). +- **Outbound**: Detects local changes, maps local data to the global ontology, resolves the owner's and/or target eVault (via the user's [eName](/docs/W3DS%20Basics/W3ID) / [Registry](/docs/Infrastructure/Registry)), and writes to the [eVault](/docs/Infrastructure/eVault) (GraphQL). - **Inbound**: Receives awareness protocol packets at `POST /api/webhook`, maps global data to the local schema, and creates or updates local entities while maintaining global-ID-to-local-ID mappings. See [Awareness Protocol](/docs/W3DS%20Protocol/Awareness-Protocol) for more details. Please Note: That neither inbound or outbound are immediate, or have any transactional guarantees. @@ -26,14 +26,14 @@ Please note that the web3 adapter may not come pre-assembled with hooks for all - **Bidirectional mapping**: Local schema ↔ global ontology via JSON mapping configs. - **ID mapping**: Stores pairs of (localId, globalId) so the same entity is recognized across sync and webhooks. When using our implementation of the Web3 Adapter, you don't need to worry about ID Mapping yourself, the adapter already handles it. -- **eVault client**: Resolves [eNames](/docs/W3DS%20Basics/W3ID) via the Registry, obtains platform tokens, and calls eVault GraphQL (store/update) with retries and health checks. +- **eVault client**: Resolves [eNames](/docs/W3DS%20Basics/W3ID) via the [Registry](/docs/Infrastructure/Registry), obtains platform tokens, and calls [eVault](/docs/Infrastructure/eVault) GraphQL (store/update) with retries and health checks. - **Change handling**: `handleChange` is the main entry for outbound sync; webhook handlers use `fromGlobal` for inbound. ## Theory: Core Ideas ### 1. Universal ontology as the common language -All platforms agree on a small set of global schemas (e.g. User, Post, Group) identified by W3IDs. Each platform maps its local tables to these schemas. The ontology is the contract: if you store data in that shape in an eVault, other platforms can interpret it via their own mappings. Better ontology design (versioning, optional fields, extensibility) leads to easier evolution and fewer breaking changes. +All platforms agree on a small set of [global schemas](/docs/Infrastructure/Ontology) (e.g. User, Post, Group) identified by W3IDs. Each platform maps its local tables to these schemas. The [ontology](/docs/Infrastructure/Ontology) is the contract: if you store data in that shape in an eVault, other platforms can interpret it via their own mappings. Better ontology design (versioning, optional fields, extensibility) leads to easier evolution and fewer breaking changes. ### 2. Per-entity owner eVault (W3ID) @@ -119,12 +119,12 @@ graph TB ### Mapping configuration (IMapping) -Mapping configs define how local fields map to the global ontology. For the full syntax (direct fields, relations, arrays, `__date`, `__calc`, owner path), see the **Web3 Adapter Mapping Rules** in the repository at `infrastructure/web3-adapter/MAPPING_RULES.md`. +Mapping configs define how local fields map to the global ontology. For the full syntax (direct fields, relations, arrays, `__date`, `__calc`, owner path), see the [Mapping Rules](/docs/Post%20Platform%20Guide/mapping-rules) or the repository at `infrastructure/web3-adapter/MAPPING_RULES.md`. Each mapping is a JSON file with: - **tableName**: Local table (or entity) name. -- **schemaId**: Global ontology UUID. +- **schemaId**: Global ontology W3ID. - **ownerEnamePath**: Path to the owner eName in the local entity (e.g. `"ename"` or `"users(createdBy.ename)"`). Supports fallbacks with `||`. - **localToUniversalMap**: Object mapping local field names to global field names or expressions (e.g. `"createdAt": "__date(createdAt)"`, relation syntax `"tableName(path),globalAlias"`). - **readOnly** (optional): If true, `handleChange` does not sync this table to the eVault. @@ -134,11 +134,15 @@ Each mapping is a JSON file with: When a platform receives an awareness protocol packet at `POST /api/webhook`: 1. Parse body: `id`, `w3id`, `schemaId`, `data`. -2. Find the mapping whose `schemaId` matches (or map by schema UUID to table name). +2. Find the mapping whose `schemaId` matches (or map by schema W3ID to table name). 3. Call `adapter.fromGlobal({ data: body.data, mapping })` to get local-shaped data. 4. Call `mappingDb.getLocalId(body.id)`; if found, update the existing local entity; otherwise create and then `mappingDb.storeMapping({ localId: newEntity.id, globalId: body.id })`. 5. Return 200. +#### fromGlobal + +`fromGlobal` is the adapter method that turns a global (ontology) payload into local-shaped data using the mapping's `localToUniversalMap`. It is used in the inbound flow above (step 3) and is the inverse of `toGlobal` used for outbound sync. + See the [Webhook Controller Guide](/docs/Post%20Platform%20Guide/webhook-controller) for a full implementation example and the [Awareness Protocol](/docs/W3DS%20Protocol/Awareness-Protocol) for the packet format and delivery mechanism. ## Sequence: Platform → Adapter → eVault @@ -172,7 +176,14 @@ sequenceDiagram ## Limitations & Planned Extensions -- **Ontology versioning**: Today `schemaId` is a single UUID, there are plans for adding a `schemaVersion` key to allow for schema versioning. +- **Ontology versioning**: Today `schemaId` is a single W3ID, there are plans for adding a `schemaVersion` key to allow for schema versioning. - **Conflict resolution**: Add version or timestamp fields and resolve conflicts in the adapter or in a separate service. - **Idempotency**: Use idempotency keys in payloads or in the mapping DB to make webhook handling and outbound sync idempotent. - **Transactional outbox**: Have the platform write changes to an outbox table and have a worker call `handleChange` so that sync is tied to the same transaction as the local write. + +## References + +- [eVault](/docs/Infrastructure/eVault) — GraphQL API and storage +- [Registry](/docs/Infrastructure/Registry) — eName resolution +- [Ontology](/docs/Infrastructure/Ontology) — Schema registry +- [Mapping Rules](/docs/Post%20Platform%20Guide/mapping-rules) — Mapping configuration syntax diff --git a/docs/docs/Infrastructure/eID-Wallet.md b/docs/docs/Infrastructure/eID-Wallet.md index 8d4dad71..8ad842b0 100644 --- a/docs/docs/Infrastructure/eID-Wallet.md +++ b/docs/docs/Infrastructure/eID-Wallet.md @@ -160,13 +160,13 @@ Verify a signature against a payload (for testing): When a new user first opens the wallet: 1. **Generate Keys**: Create default key pair (hardware keys for real users, software keys only for pre-verification/test users) -2. **Request Entropy**: Get entropy token from Registry -3. **Generate Namespace**: Create UUID for namespace -4. **Provision eVault**: Send provision request with public key to the Provisioner service (not to eVault Core, as no eVault exists yet, and not to Registry) +2. **Request Entropy**: Get entropy token from [Registry](/docs/Infrastructure/Registry) +3. **Generate Namespace**: Create a unique identifier for namespace +4. **Provision eVault**: Send provision request with public key to the [Provisioner](/docs/W3DS%20Basics/Links) service (not to eVault Core, as no eVault exists yet, and not to Registry) 5. **Receive Credentials**: Get W3ID (eName) and eVault URI 6. **Store Locally**: Save credentials in wallet storage -**API Flow**: +**API Flow** (see [Registry](/docs/Infrastructure/Registry) for entropy and key binding): ``` Wallet → Registry: GET /entropy Registry → Wallet: JWT entropy token @@ -201,7 +201,7 @@ For detailed information on: - Uses key ID `"default"` - Uses context `"onboarding"` for real users (always hardware keys) or `"pre-verification"` for fake/test users (software keys) - For real KYC-verified users: Always uses hardware keys, never software keys -- Signs the exact session ID string (UUID) +- Signs the exact session ID string - Returns base64 or multibase-encoded signature ### Key Rotation (Conceptual - Not Yet Implemented) @@ -224,7 +224,7 @@ Public keys must be synced to eVault so platforms can verify signatures. 1. **Get Public Key**: Retrieve public key from key manager 2. **Format**: Ensure public key is in multibase format 3. **Send to eVault**: POST to eVault's key storage endpoint -4. **Certificate Generation**: eVault requests key binding certificate from Registry +4. **Certificate Generation**: [eVault](/docs/Infrastructure/eVault) requests key binding certificate from [Registry](/docs/Infrastructure/Registry) 5. **Storage**: Certificate stored in eVault for future verification ### Sync Timing @@ -240,7 +240,7 @@ The wallet creates signatures for various purposes: **Purpose**: Prove identity to platforms -**Payload**: Session ID (UUID string) +**Payload**: Session ID (string) **Process**: 1. Platform generates session ID @@ -404,6 +404,9 @@ const { token } = await response.json(); ## References +- [Registry](/docs/Infrastructure/Registry) - Entropy and key binding certificates +- [W3ID](/docs/W3DS%20Basics/W3ID) - Identifiers and eName resolution +- [Links](/docs/W3DS%20Basics/Links) - Production URLs (Provisioner, Registry, Ontology) - [Authentication](/docs/W3DS%20Protocol/Authentication) - How wallet authentication works - [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation details - [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical signature format details diff --git a/docs/docs/Infrastructure/eVault-Key-Delegation.md b/docs/docs/Infrastructure/eVault-Key-Delegation.md index b7feb9bc..79b41b6f 100644 --- a/docs/docs/Infrastructure/eVault-Key-Delegation.md +++ b/docs/docs/Infrastructure/eVault-Key-Delegation.md @@ -8,7 +8,7 @@ This document explains how the eVault system delegates cryptographic keys for si ## Overview -The eVault system enables users to sign data using keys stored in their eID wallet. The public keys are synced to eVault and bound to the user's eName (W3ID) through key binding certificates. This allows any service to verify signatures by retrieving the public key from eVault. +The eVault system enables users to sign data using keys stored in their [eID wallet](/docs/Infrastructure/eID-Wallet). The public keys are synced to [eVault](/docs/Infrastructure/eVault) and bound to the user's eName (W3ID) through [key binding certificates](/docs/Infrastructure/eVault#key-binding-certificates) (issued by the [Registry](/docs/Infrastructure/Registry)). This allows any service to verify signatures by retrieving the public key from eVault. ## Key Delegation Flow @@ -34,7 +34,7 @@ Content-Type: application/json { "registryEntropy": "", - "namespace": "", + "namespace": "", "verificationId": "", "publicKey": "z3059301306072a8648ce3d020106082a8648ce3d03010703420004..." } @@ -93,7 +93,7 @@ sequenceDiagram ### 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. +Key binding certificates are JWTs that cryptographically bind a public key to an eName. They are generated by the [Registry](/docs/Infrastructure/Registry) service and stored in [eVault](/docs/Infrastructure/eVault). **Certificate Structure:** - **Header**: `{ alg: "ES256", kid: "entropy-key-1" }` @@ -104,6 +104,8 @@ The certificate can be verified using the Registry's JWKS endpoint at `/.well-kn ### eVault Endpoints +The following endpoints are provided by [eVault](/docs/Infrastructure/eVault): + #### PATCH /public-key Stores a public key in eVault for a given eName. @@ -208,3 +210,9 @@ const certificates = whoisResponse.data.keyBindingCertificates; 3. **Multiple Keys**: Users can have multiple devices, each with its own key pair. All valid keys can verify signatures. 4. **Key Rotation**: When users add new devices, new keys are added without invalidating old ones, allowing graceful key rotation. + +## References + +- [eID Wallet](/docs/Infrastructure/eID-Wallet) - Key generation and syncing +- [eVault](/docs/Infrastructure/eVault) - Storage, `/whois`, and key binding +- [Registry](/docs/Infrastructure/Registry) - Key binding certificate issuance diff --git a/docs/docs/Infrastructure/eVault.md b/docs/docs/Infrastructure/eVault.md index e0ba9de8..445df571 100644 --- a/docs/docs/Infrastructure/eVault.md +++ b/docs/docs/Infrastructure/eVault.md @@ -8,7 +8,7 @@ eVault is the core storage system for W3DS. It provides a GraphQL API for storin ## Overview -An **eVault** is a personal data store identified by a **W3ID**. Each user, group, or object has their own eVault where all their data is stored in a standardized format called **MetaEnvelopes**. +An **eVault** is a personal data store identified by a [W3ID](/docs/W3DS%20Basics/W3ID). Each user, group, or object has their own eVault where all their data is stored in a standardized format called **MetaEnvelopes**. ### Key Features @@ -40,7 +40,7 @@ graph TB end subgraph External["External Services"] - Registry[Registry Service
W3ID Resolution] + Registry[Registry
W3ID Resolution] end Platform -->|GraphQL Mutations/Queries| GraphQL @@ -63,8 +63,8 @@ graph TB A **MetaEnvelope** is the top-level container for an entity (post, user, message, etc.). It contains: -- **id**: Unique identifier (UUID). Note: Only IDs registered in the Registry are guaranteed to be globally unique. -- **ontology**: Schema identifier (UUID, e.g., "550e8400-e29b-41d4-a716-446655440001"). Ontology UUIDs can be resolved to their schema definitions via the ontology service. See [W3DS Basics](/docs/W3DS%20Basics/getting-started) for more information on ontology schemas. +- **id**: Unique identifier (W3ID). Note: Only IDs registered in the Registry are guaranteed to be globally unique. +- **ontology**: Schema identifier (W3ID, e.g., "550e8400-e29b-41d4-a716-446655440001"). Schema W3IDs can be resolved to their schema definitions via the [Ontology](/docs/Infrastructure/Ontology) service. See [W3DS Basics](/docs/W3DS%20Basics/getting-started) for more information on ontology schemas. - **acl**: Access Control List (who can access this data) - **envelopes**: Array of individual Envelope nodes @@ -303,7 +303,7 @@ ACLs are arrays of W3IDs or special values: The Access Guard middleware enforces ACLs: -1. **Extract W3ID**: From `X-ENAME` header or Bearer token +1. **Extract W3ID**: From `X-ENAME` header or [Bearer token](/docs/W3DS%20Protocol/Authentication) 2. **Check ACL**: Verify the requesting W3ID is in the MetaEnvelope's ACL 3. **Filter Results**: Remove ACL field from responses (security) 4. **Allow/Deny**: Grant or deny access based on ACL @@ -322,9 +322,9 @@ When data is stored or updated, eVault automatically sends webhooks to all regis 1. **Data Stored**: MetaEnvelope is stored in Neo4j 2. **Wait 3 Seconds**: Delay prevents webhook ping-pong (same platform receiving its own webhook) -3. **Get Active Platforms**: Query Registry for list of active platforms +3. **Get Active Platforms**: Query [Registry](/docs/Infrastructure/Registry) for list of active platforms 4. **Filter Requesting Platform**: Exclude the platform that made the request -5. **Send Webhooks**: POST to each platform's `/api/webhook` endpoint +5. **Send Webhooks**: POST to each platform's `/api/webhook` endpoint (see [Webhook Controller Guide](/docs/Post%20Platform%20Guide/webhook-controller)) ### Webhook Payload @@ -354,9 +354,9 @@ When data is stored or updated, eVault automatically sends webhooks to all regis eVault stores public keys for users and issues **key binding certificates** (JWTs) that bind public keys to W3IDs. These certificates serve two important purposes: -1. **Tamper Protection**: Even if HTTPS is not used (though it should be), the JWT signature prevents tampering with public keys in transit. The Registry signs each certificate, ensuring the public key hasn't been modified. +1. **Tamper Protection**: Even if HTTPS is not used (though it should be), the JWT signature prevents tampering with public keys in transit. The [Registry](/docs/Infrastructure/Registry) signs each certificate, ensuring the public key hasn't been modified. -2. **Registry Accountability**: The Registry is accountable for the W3ID-to-public-key binding. By signing the certificates, the Registry attests to the binding between a W3ID and a public key, preventing spoofing of W3ID resolution. +2. **Registry Accountability**: The [Registry](/docs/Infrastructure/Registry) is accountable for the W3ID-to-public-key binding. By signing the certificates, the Registry attests to the binding between a W3ID and a public key, preventing spoofing of W3ID resolution. ### Certificate Structure @@ -423,5 +423,10 @@ curl -X GET http://localhost:4000/whois \ ## References - [W3DS Basics](/docs/W3DS%20Basics/getting-started) - Understanding eVault ownership +- [W3ID](/docs/W3DS%20Basics/W3ID) - Identifiers and eName resolution +- [Registry](/docs/Infrastructure/Registry) - W3ID resolution and key binding +- [Ontology](/docs/Infrastructure/Ontology) - Schema registry +- [eID Wallet](/docs/Infrastructure/eID-Wallet) - Key management and provisioning +- [Links](/docs/W3DS%20Basics/Links) - Production service URLs - [Authentication](/docs/W3DS%20Protocol/Authentication) - How platforms authenticate users - [Signing](/docs/W3DS%20Protocol/Signing) - Signature verification using eVault keys diff --git a/docs/docs/Post Platform Guide/_category_.json b/docs/docs/Post Platform Guide/_category_.json index 92fe14e1..b3f0b69c 100644 --- a/docs/docs/Post Platform Guide/_category_.json +++ b/docs/docs/Post Platform Guide/_category_.json @@ -1,7 +1,4 @@ { "label": "Post Platforms Guide", - "position": 5, - "link": { - "type": "generated-index" - } + "position": 5 } \ No newline at end of file diff --git a/docs/docs/Post Platform Guide/getting-started.md b/docs/docs/Post Platform Guide/getting-started.md index bafe0fdb..9c217cda 100644 --- a/docs/docs/Post Platform Guide/getting-started.md +++ b/docs/docs/Post Platform Guide/getting-started.md @@ -9,15 +9,15 @@ This guide will help you get started building platforms in the metastate ecosyst ## Overview Platforms in the metastate ecosystem follow a standard architecture pattern: -1. **Authentication** - Users authenticate using their W3ID (Web3 Identity) via the `w3ds://auth` protocol -2. **Webhooks** - Platform data syncs from the global eVault system via webhooks -3. **Mappings** - Data transformation between global ontology and local database schemas +1. **[Authentication](/docs/W3DS%20Protocol/Authentication)** — Users authenticate using their W3ID (Web3 Identity) via the `w3ds://auth` protocol +2. **[Webhooks](/docs/Post%20Platform%20Guide/webhook-controller)** — Platform data syncs from the global eVault system via webhooks +3. **[Mappings](/docs/Post%20Platform%20Guide/mapping-rules)** — Data transformation between global ontology and local database schemas This document focuses on authentication. For webhooks and mappings, see the other documentation files. ## Authentication -All platforms use a signature-based authentication system that leverages users' existing ename and keys attached to that. The authentication flow follows the `w3ds://auth` protocol. +All platforms use a signature-based authentication system that leverages users' existing ename and keys attached to that. The authentication flow follows the [`w3ds://auth`](/docs/W3DS%20Protocol/Authentication) protocol. ### Authentication Flow @@ -55,7 +55,7 @@ getOffer = async (req: Request, res: Response) => { } ``` -The client opens this URL in a w3ds-compatible client (like eID Wallet), which handles the user's signature and redirects back to your platform. +The client opens this URL in a w3ds-compatible client (like the [eID Wallet](/docs/Infrastructure/eID-Wallet)), which handles the user's signature and redirects back to your platform. #### 2. Login Endpoint (`POST /api/auth`) @@ -76,7 +76,7 @@ This endpoint receives the authentication result from the w3ds client and verifi login = async (req: Request, res: Response) => { const { ename, session, signature } = req.body; - // Verify signature using signature-validator + // Verify signature using signature-validator (see [Signing](/docs/W3DS%20Protocol/Signing) / [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats)) const verificationResult = await verifySignature({ eName: ename, signature: signature, @@ -96,7 +96,7 @@ login = async (req: Request, res: Response) => { if (!user) { return res.status(404).json({ error: "User not found", - message: "User must be created via eVault webhook before authentication" + message: "User must be created via [eVault](/docs/Infrastructure/eVault) [webhook](/docs/Post%20Platform%20Guide/webhook-controller) before authentication" }); } @@ -112,11 +112,11 @@ login = async (req: Request, res: Response) => { **Key points:** - The `session` string is what was signed by the user -- Signature verification uses the `signature-validator` package, which: - - Fetches the user's public key from their eVault +- Signature verification uses the `signature-validator` package (see [Signing](/docs/W3DS%20Protocol/Signing)), which: + - Fetches the user's public key from their [eVault](/docs/Infrastructure/eVault) - Verifies the signature using Web Crypto API - Supports multiple signature formats (multibase, base64, etc.) -- Users must exist in your database before they can authenticate (created via webhooks) +- Users must exist in your database before they can authenticate (created via [webhooks](/docs/Post%20Platform%20Guide/webhook-controller)) - The JWT token contains the `userId` and expires in 7 days #### 3. JWT Token Generation @@ -217,3 +217,13 @@ JWT_SECRET=your-secret-key-here # Registry base URL for signature verification PUBLIC_REGISTRY_URL=https://registry.example.com +## References + +- [Authentication](/docs/W3DS%20Protocol/Authentication) — w3ds://auth protocol +- [Signing](/docs/W3DS%20Protocol/Signing) — Signature creation and verification +- [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) — Cryptographic details +- [Webhook Controller](/docs/Post%20Platform%20Guide/webhook-controller) — Receiving webhooks +- [Mapping Rules](/docs/Post%20Platform%20Guide/mapping-rules) — Schema mapping +- [eVault](/docs/Infrastructure/eVault) — Storage and key binding +- [Registry](/docs/Infrastructure/Registry) — W3ID resolution and JWKS + diff --git a/docs/docs/Post Platform Guide/mapping-rules.md b/docs/docs/Post Platform Guide/mapping-rules.md index 87f23fb2..d000ef31 100644 --- a/docs/docs/Post Platform Guide/mapping-rules.md +++ b/docs/docs/Post Platform Guide/mapping-rules.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Mapping Rules -This document explains how to create mappings for the web3-adapter system, which enables data exchange between different platforms using a universal ontology. +This document explains how to create mappings for the [Web3 Adapter](/docs/Infrastructure/Web3-Adapter) system, which enables data exchange between different platforms using the [universal ontology](/docs/Infrastructure/Ontology). ## Basic Structure @@ -13,7 +13,7 @@ A mapping file defines how local database fields map to global ontology fields. ```json { "tableName": "local_table_name", - "schemaId": "global_schema_uuid", + "schemaId": "global_schema_w3id", "ownerEnamePath": "path_to_owner_ename", "ownedJunctionTables": ["junction_table1", "junction_table2"], "localToUniversalMap": { @@ -94,7 +94,7 @@ Performs mathematical calculations using field values. ## Owner Path -The `ownerEnamePath` defines how to determine which eVault owns the data: +The `ownerEnamePath` defines how to determine which [eVault](/docs/Infrastructure/eVault) owns the data (via the owner's [eName](/docs/W3DS%20Basics/W3ID)): ```json "ownerEnamePath": "ename" // Direct field @@ -181,3 +181,9 @@ When junction table data changes, it triggers updates to the parent entity. - Test with simple data first, then add complexity - Use the `__calc()` function to debug field values +## References + +- [Web3 Adapter](/docs/Infrastructure/Web3-Adapter) — Bridge between platform DB and eVault +- [Ontology](/docs/Infrastructure/Ontology) — Schema registry and schemaIds +- [Webhook Controller](/docs/Post%20Platform%20Guide/webhook-controller) — Using mappings for inbound webhooks + diff --git a/docs/docs/Post Platform Guide/webhook-controller.md b/docs/docs/Post Platform Guide/webhook-controller.md index 264ec1c4..e372f952 100644 --- a/docs/docs/Post Platform Guide/webhook-controller.md +++ b/docs/docs/Post Platform Guide/webhook-controller.md @@ -4,7 +4,7 @@ sidebar_position: 3 # Webhook Controller Guide -The webhook controller receives awareness protocol packets from the eVault system and saves them to your local database. +The webhook controller receives [awareness protocol](/docs/W3DS%20Protocol/Awareness-Protocol) packets from the [eVault](/docs/Infrastructure/eVault) system and saves them to your local database. ## What the Webhook Receives @@ -13,7 +13,7 @@ The webhook endpoint (`POST /api/webhook`) receives awareness protocol packets w ```json { "id": "global-id-123", - "schemaId": "uuid-of-schema", + "schemaId": "schema-w3id", "w3id": "https://evault.example.com/users/123", "data": { "displayName": "John Doe", @@ -23,7 +23,7 @@ The webhook endpoint (`POST /api/webhook`) receives awareness protocol packets w } ``` -The `schemaId` identifies which mapping to use for transforming the data, and `data` contains the entity information in the global ontology format. +The `schemaId` (see [Ontology](/docs/Infrastructure/Ontology)) identifies which [mapping](/docs/Post%20Platform%20Guide/mapping-rules) to use for transforming the data, and `data` contains the entity information in the global ontology format. ## What to Do @@ -34,7 +34,7 @@ const mapping = Object.values(this.adapter.mapping).find( ); ``` -2. **Convert from global to local** using the adapter's `fromGlobal` method: +2. **Convert from global to local** using the [Web3 Adapter](/docs/Infrastructure/Web3-Adapter)'s `fromGlobal` method: ```typescript const local = await this.adapter.fromGlobal({ data: req.body.data, @@ -42,7 +42,7 @@ const local = await this.adapter.fromGlobal({ }); ``` -This method uses your mapping configuration to transform the global ontology data into your local database schema format. See the [Mapping Rules documentation](./mapping-rules.md) for details on creating mappings. +This method uses your mapping configuration to transform the global ontology data into your local database schema format. See the [Mapping Rules](/docs/Post%20Platform%20Guide/mapping-rules) for details on creating mappings. 3. **Check if entity exists** using the global ID: ```typescript @@ -106,3 +106,10 @@ handleWebhook = async (req: Request, res: Response) => { } }; +## References + +- [Awareness Protocol](/docs/W3DS%20Protocol/Awareness-Protocol) — Webhook payload and delivery +- [eVault](/docs/Infrastructure/eVault) — Webhook delivery from eVault +- [Ontology](/docs/Infrastructure/Ontology) — Schema IDs and schema registry +- [Web3 Adapter](/docs/Infrastructure/Web3-Adapter) — `fromGlobal` and mapping + diff --git a/docs/docs/W3DS Basics/Links.md b/docs/docs/W3DS Basics/Links.md new file mode 100644 index 00000000..033ae17d --- /dev/null +++ b/docs/docs/W3DS Basics/Links.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 3 +--- + +# Links + +Production base URLs for core W3DS infrastructure services. + +| Service | Base URL | +|---------|----------| +| **Provisioner** | [https://provisioner.w3ds.metastate.foundation](https://provisioner.w3ds.metastate.foundation) | +| **Registry** | [https://registry.w3ds.metastate.foundation](https://registry.w3ds.metastate.foundation) | +| **Ontology** | [https://ontology.w3ds.metastate.foundation](https://ontology.w3ds.metastate.foundation) | + +- **Provisioner**: [eVault provisioning](/docs/Infrastructure/eID-Wallet#onboarding-and-evault-creation) (e.g. creating a new eVault for a user). +- **Registry**: W3ID resolution, entropy, platform discovery, and (temporarily) key binding. See [Registry](/docs/Infrastructure/Registry). +- **Ontology**: Schema registry; list and fetch JSON schemas by W3ID. See [Ontology](/docs/Infrastructure/Ontology). diff --git a/docs/docs/W3DS Basics/W3ID.md b/docs/docs/W3DS Basics/W3ID.md index d47b9cb4..e8aac6f4 100644 --- a/docs/docs/W3DS Basics/W3ID.md +++ b/docs/docs/W3DS Basics/W3ID.md @@ -4,7 +4,7 @@ sidebar_position: 2 # W3ID -W3ID (Web 3 Identifier) is the main identifier for the whole W3DS ecosystem. W3IDs are UUID-based, persistent, and globally unique. When the term **eName** is used, it means a universally resolvable W3ID—one that can be resolved via the Registry to an eVault (or service) endpoint. +W3ID (Web 3 Identifier) is the main identifier for the whole W3DS ecosystem. W3IDs are UUID-based, persistent, and globally unique. When the term **eName** is used, it means a universally resolvable W3ID—one that can be resolved via the [Registry](/docs/Infrastructure/Registry) to an eVault (or service) endpoint. ## Overview @@ -27,7 +27,7 @@ The UUID namespace has range 2^122, which is far larger than the expected number ## Registry Resolution (eName) -What makes a W3ID an **eName** is that it is registered in the Registry and can be resolved to a service URL: +What makes a W3ID an **eName** is that it is registered in the [Registry](/docs/Infrastructure/Registry) and can be resolved to a service URL: 1. A client sends `GET /resolve?w3id=@e4d909c2-5d2f-4a7d-9473-b34b6c0f1a5a` to the Registry. 2. The Registry returns the eVault (or controller) URL for that W3ID. @@ -62,10 +62,10 @@ graph LR ``` - **Users and groups**: Each has a persistent W3ID (typically an eName). For a person, the W3ID is the long-lived anchor that connects keys (eID certificate, PKI) and the physical person (body characteristics, passport, friends). -- **eVaults**: An eVault may have its own internal W3ID used for syncing between clones or by the hosting provider; the user’s eName is what identifies the “owner” of the vault. -- **MetaEnvelopes**: Each envelope has an owner (a W3ID/eName) and an optional global ID; the W3ID URI scheme can be used to refer to an envelope (e.g. `@/`). -- **ACLs**: Access control lists reference W3IDs (eNames) to indicate who can access data. -- **Key binding**: Public keys in the eVault are bound to the user’s W3ID (eName) via key binding certificates. +- **eVaults**: An [eVault](/docs/Infrastructure/eVault) may have its own internal W3ID used for syncing between clones or by the hosting provider; the user’s eName is what identifies the “owner” of the vault. +- **MetaEnvelopes**: Each envelope has an owner (a W3ID/eName) and an optional global ID; see [eVault](/docs/Infrastructure/eVault). The W3ID URI scheme can be used to refer to an envelope (e.g. `@/`). +- **ACLs**: [Access control lists](/docs/Infrastructure/eVault#access-control) reference W3IDs (eNames) to indicate who can access data. +- **Key binding**: Public keys in the eVault are bound to the user’s W3ID (eName) via [key binding certificates](/docs/Infrastructure/eVault#key-binding-certificates) (issued by the [Registry](/docs/Infrastructure/Registry)). ## Key Binding and Recovery @@ -73,11 +73,11 @@ The identifier is **loosely bound** to a set of keys: the W3ID is not derived fr - **Key rotation**: Keys can be changed (e.g. after compromise or device loss) without changing the W3ID. - **Friend-based recovery**: A trust list (e.g. 2–3 friends or notaries) can verify identity and approve key changes. The user defines this list while they still have access to their keys. -- **eVault migration**: When a user migrates from one eVault to another, the Registry can store also-known-as (redirect) records so that resolution of the same eName continues to work (e.g. requests for the old eVault W3ID are redirected to the new eVault). +- **eVault migration**: When a user migrates from one eVault to another, the [Registry](/docs/Infrastructure/Registry) can store also-known-as (redirect) records so that resolution of the same eName continues to work (e.g. requests for the old eVault W3ID are redirected to the new eVault). ## Document Binding -The identifier can be loosely bound to a passport via a binding document certified by a root CA, where the identifier is connected to entropy derived from passport details. Passport verification itself is out of scope for W3ID and is handled by the eID Wallet application. +The identifier can be loosely bound to a passport via a binding document certified by a root CA, where the identifier is connected to entropy derived from passport details. Passport verification itself is out of scope for W3ID and is handled by the [eID Wallet](/docs/Infrastructure/eID-Wallet) application. ## Technical Requirements and Guarantees @@ -98,3 +98,9 @@ This package is useful to create W3IDs with keys or make them global, it is consumed currently by [eID Wallet](/docs/Infrastructure/eID-Wallet) and [Web3 Adapter](/docs/Infrastructure/Web3-Adapter) For implementation details (builder API, storage backends, logging format), see the `w3id` package in the repository. + +## References + +- [Registry](/docs/Infrastructure/Registry) — eName resolution and key binding +- [eVault](/docs/Infrastructure/eVault) — Storage, ACLs, and key binding certificates +- [eID Wallet](/docs/Infrastructure/eID-Wallet) — Key management and onboarding diff --git a/docs/docs/W3DS Basics/_category_.json b/docs/docs/W3DS Basics/_category_.json index 9cbceaf6..15f82acc 100644 --- a/docs/docs/W3DS Basics/_category_.json +++ b/docs/docs/W3DS Basics/_category_.json @@ -1,7 +1,4 @@ { "label": "W3DS Basics", - "position": 2, - "link": { - "type": "generated-index" - } + "position": 2 } diff --git a/docs/docs/W3DS Basics/getting-started.md b/docs/docs/W3DS Basics/getting-started.md index 3bfe6e6a..e922cb60 100644 --- a/docs/docs/W3DS Basics/getting-started.md +++ b/docs/docs/W3DS Basics/getting-started.md @@ -12,7 +12,7 @@ In W3DS, **every user, group, and object owns their own eVault**. This is the fu ### What is an eVault? -An **eVault** is a personal data store identified by a **W3ID** (also called an **eName**). It's where all data about a person, group, or object is stored in a standardized format called **MetaEnvelopes**. +An **eVault** is a personal data store identified by a [W3ID](/docs/W3DS%20Basics/W3ID) (also called an **eName**). It's where all data about a person, group, or object is stored in a standardized format called [MetaEnvelopes](/docs/Infrastructure/eVault#data-model). ### Ownership Structure @@ -98,7 +98,7 @@ The adapter makes an HTTP POST request to the eVault's GraphQL endpoint. The req **HTTP Request Details**: - **Method**: POST -- **URL**: `{evaultUrl}/graphql` (where evaultUrl is resolved from the user's eName via Registry) +- **URL**: `{evaultUrl}/graphql` (where evaultUrl is resolved from the user's [eName](/docs/W3DS%20Basics/W3ID) via [Registry](/docs/Infrastructure/Registry)) - **Headers**: - `Content-Type: application/json` - `X-ENAME: @user-a.w3id` (the owner's eName) @@ -143,11 +143,11 @@ mutation StoreMetaEnvelope($input: MetaEnvelopeInput!) { #### 5. eVault Stores MetaEnvelope -The eVault stores the data as a MetaEnvelope, which is a flat graph structure of Envelopes. Each field becomes a separate Envelope node in Neo4j. +The [eVault](/docs/Infrastructure/eVault) stores the data as a [MetaEnvelope](/docs/Infrastructure/eVault#data-model), which is a flat graph structure of Envelopes. Each field becomes a separate Envelope node in Neo4j. #### 6. Webhook Delivery (After 3 Second Delay) -After a 3-second delay (to prevent webhook ping-pong), the eVault sends webhooks to all registered platforms **except** the one that made the request (Blabsy). +After a 3-second delay (to prevent webhook ping-pong), the [eVault](/docs/Infrastructure/eVault) sends webhooks to all registered platforms (see [Registry](/docs/Infrastructure/Registry)) **except** the one that made the request (Blabsy). The webhook payload contains: ```json @@ -224,7 +224,7 @@ Every webhook contains: - **id**: The global ID of the MetaEnvelope - **w3id**: The eName (W3ID) of the owner -- **schemaId**: The ontology schema ID (UUID) +- **schemaId**: The ontology schema ID (W3ID) - **data**: The actual data in global ontology format - **evaultPublicKey**: The eVault's public key (for verification) @@ -253,12 +253,12 @@ A **MetaEnvelope** is the storage format in eVaults. It's a flat graph structure ### Ontology Schemas -**Ontology schemas** define the global data format. They're JSON Schema files that specify: +[Ontology schemas](/docs/Infrastructure/Ontology) define the global data format. They're JSON Schema files that specify: - Field names and types - Required fields - Validation rules -- Schema IDs (UUIDs) +- Schema IDs (W3IDs) — see [Ontology](/docs/Infrastructure/Ontology) for the schema registry Example: `SocialMediaPost` schema defines fields like `content`, `mediaUrls`, `authorId`, etc. @@ -266,16 +266,16 @@ All platforms must map their local schemas to these global schemas. See [Mapping ## W3ID (eName) System -**W3ID** (also called **eName**) is the persistent identifier for users, groups, and objects. +[W3ID](/docs/W3DS%20Basics/W3ID) (also called **eName**) is the persistent identifier for users, groups, and objects. ### Format -- Global IDs: `@` (e.g., `@e4d909c2-5d2f-4a7d-9473-b34b6c0f1a5a`) -- Local IDs: `@/` (for objects within an eVault) +- Global IDs: `@` (e.g., `@e4d909c2-5d2f-4a7d-9473-b34b6c0f1a5a`) +- Local IDs: `@/` (for objects within an eVault) ### Resolution -W3IDs are resolved to eVault URLs via the Registry Service: +W3IDs are resolved to eVault URLs via the [Registry Service](/docs/Infrastructure/Registry): ``` GET /resolve?w3id=@user-a.w3id @@ -285,7 +285,7 @@ GET /resolve?w3id=@user-a.w3id ### Key Properties 1. **Persistent**: Never changes, even if eVault URL changes -2. **Globally Unique**: UUID-based ensures uniqueness +2. **Globally Unique**: W3ID-based ensures uniqueness 3. **Loosely Bound to Keys**: Can rotate keys without changing W3ID 4. **Resolvable**: Registry maps W3ID to current eVault URL @@ -293,7 +293,7 @@ GET /resolve?w3id=@user-a.w3id ### Access Control Lists (ACLs) -ACLs determine who can access data in an eVault. Common patterns: +[ACLs](/docs/Infrastructure/eVault#access-control) determine who can access data in an eVault. Common patterns: - `["*"]`: Public access (anyone can read) - `["@user-a.w3id"]`: Only User A can access @@ -353,6 +353,8 @@ graph LR ## Next Steps +- [Links](/docs/W3DS%20Basics/Links) — Production URLs for Provisioner, Registry, Ontology +- [Ontology](/docs/Infrastructure/Ontology) — Schema registry and available schemas - Learn about [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate - Understand [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification - Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Cryptographic details diff --git a/docs/docs/W3DS Protocol/Authentication.md b/docs/docs/W3DS Protocol/Authentication.md index da0e1017..cca35fe2 100644 --- a/docs/docs/W3DS Protocol/Authentication.md +++ b/docs/docs/W3DS Protocol/Authentication.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Authentication -W3DS uses cryptographic signature-based authentication. Users authenticate with platforms by signing a session ID with their private key, which platforms verify using public keys stored in eVaults. +W3DS uses cryptographic signature-based authentication. Users authenticate with platforms by signing a session ID with their private key, which platforms verify using public keys stored in [eVaults](/docs/Infrastructure/eVault). ## Overview @@ -12,8 +12,8 @@ Unlike traditional password-based authentication, W3DS uses **cryptographic sign - **No passwords**: Users never share secrets with platforms - **Cryptographic proof**: Platforms can cryptographically verify user identity -- **Key-based**: Uses ECDSA P-256 keys managed by the eID wallet -- **Decentralized**: Public keys stored in user's eVault, verified via Registry +- **Key-based**: Uses ECDSA P-256 keys managed by the [eID wallet](/docs/Infrastructure/eID-Wallet) +- **Decentralized**: Public keys stored in user's [eVault](/docs/Infrastructure/eVault), verified via [Registry](/docs/Infrastructure/Registry) ## Authentication Flow @@ -57,7 +57,7 @@ sequenceDiagram When a user wants to log in, the platform must: -1. **Generate a unique session identifier**: Use a cryptographically secure random UUID (version 4). This session ID will be signed by the user, so it must be unique and unpredictable. +1. **Generate a unique session identifier**: Use a cryptographically secure random session ID (128-bit). This session ID will be signed by the user, so it must be unique and unpredictable. 2. **Construct the redirect URL**: Build the full URL where the eID wallet will POST the signed session data. This is typically `{platformBaseUrl}/api/auth/login` or similar. The wallet will make an HTTP POST request to this URL with the signed authentication data. @@ -66,7 +66,7 @@ When a user wants to log in, the platform must: w3ds://auth?redirect={redirectUrl}&session={sessionId}&platform={platformName} ``` - `redirect`: URL-encoded redirect endpoint where the eID wallet will POST the signed session (this is the callback URL) - - `session`: The generated session UUID + - `session`: The generated session ID - `platform`: Platform identifier (for display purposes) 4. **Return JSON response**: Send a JSON object with the `uri` field containing the w3ds://auth URI. @@ -83,7 +83,7 @@ When a user wants to log in, the platform must: ``` **Implementation Requirements**: -- Generate UUID v4 (128-bit random UUID) +- Generate a cryptographically secure random session ID (128-bit) - URL-encode the redirect parameter - Return JSON with Content-Type: application/json - Store the session ID temporarily (in memory, cache, or database) to validate it later @@ -105,7 +105,7 @@ getOffer = async (req: Request, res: Response) => { 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. +1. **Parse the w3ds://auth URI**: Extract the `session` parameter from the query string. The session ID must be signed exactly as received. 2. **Hash the session ID**: Convert the session ID string to bytes using UTF-8 encoding, then compute SHA-256 hash. This produces a 32-byte hash digest. @@ -156,7 +156,7 @@ After the user signs the session ID, the eID wallet makes an HTTP POST request t **Field Descriptions**: - `w3id`: The user's W3ID (eName) identifier, always starts with '@' -- `session`: The session UUID that was generated in Step 1 +- `session`: The session ID that was generated in Step 1 - `signature`: The base64 or multibase-encoded signature of the session ID - `appVersion`: Optional version string for compatibility checking @@ -385,7 +385,7 @@ export class AuthController { ### 1. Session ID Uniqueness -- Session IDs must be **cryptographically random** (use UUID v4) +- Session IDs must be **cryptographically random** (e.g. 128-bit random) - Each session ID should be used **only once** - Expire session IDs after a reasonable time (e.g., 5 minutes) @@ -437,5 +437,8 @@ By enforcing uniqueness, one-time use, and expiration, platforms ensure that eve ## References +- [eVault](/docs/Infrastructure/eVault) — Public keys and key binding certificates +- [Registry](/docs/Infrastructure/Registry) — W3ID resolution and JWKS +- [eID Wallet](/docs/Infrastructure/eID-Wallet) — Key management and signing - [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification details - [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Detailed signature format documentation diff --git a/docs/docs/W3DS Protocol/Awareness-Protocol.md b/docs/docs/W3DS Protocol/Awareness-Protocol.md index 0a94a985..36047a31 100644 --- a/docs/docs/W3DS Protocol/Awareness-Protocol.md +++ b/docs/docs/W3DS Protocol/Awareness-Protocol.md @@ -8,11 +8,11 @@ sidebar_position: 4 The Awareness Protocol described here is **prototype-level**. The packet format, delivery behavior, and platform contract are subject to change in upcoming updates ::: -The Awareness Protocol is the webhook delivery mechanism in W3DS. When data in an eVault changes (create or update), the eVault notifies every registered platforms so they can stay in sync. "Awareness" means platforms become aware of changes that happened elsewhere. +The Awareness Protocol is the webhook delivery mechanism in W3DS. When data in an [eVault](/docs/Infrastructure/eVault) changes (create or update), the eVault notifies every registered platform so they can stay in sync. "Awareness" means platforms become aware of changes that happened elsewhere. ## Overview -Platforms do not poll eVaults for changes. Instead, eVault Core pushes change notifications to every registered platform (except the one that originated the change) via HTTP POST to each platform's `/api/webhook` endpoint. The payload is called an **awareness protocol packet**. Platforms use this packet to apply the same change locally (e.g. create or update an entity in their database) and to maintain ID mappings between global and local IDs. +Platforms do not poll eVaults for changes. Instead, [eVault](/docs/Infrastructure/eVault) Core pushes change notifications to every registered platform (except the one that originated the change) via HTTP POST to each platform's `/api/webhook` endpoint. The payload is called an **awareness protocol packet**. Platforms use this packet to apply the same change locally (e.g. create or update an entity in their database) and to maintain ID mappings between global and local IDs. ### Key Properties @@ -25,8 +25,8 @@ Platforms do not poll eVaults for changes. Instead, eVault Core pushes change no The Awareness Protocol is triggered after: -1. **storeMetaEnvelope** (create): After the new MetaEnvelope is stored in the eVault, webhooks are **scheduled with a 3-second delay** to ensure the requesting platform can be reliably identified and excluded from recipients, preventing the same platform from receiving its own write-back and creating a feedback loop ("webhook ping-pong"). -2. **updateMetaEnvelopeById** (update): After the MetaEnvelope is updated, webhooks are sent **immediately** (fire-and-forget, no delay). +1. **[storeMetaEnvelope](/docs/Infrastructure/eVault#graphql-api)** (create): After the new MetaEnvelope is stored in the eVault, webhooks are **scheduled with a 3-second delay** to ensure the requesting platform can be reliably identified and excluded from recipients, preventing the same platform from receiving its own write-back and creating a feedback loop ("webhook ping-pong"). +2. **[updateMetaEnvelopeById](/docs/Infrastructure/eVault#graphql-api)** (update): After the MetaEnvelope is updated, webhooks are sent **immediately** (fire-and-forget, no delay). ## Mechanism @@ -53,7 +53,7 @@ sequenceDiagram ### Step-by-Step -1. **Platform list**: eVault calls the Registry with `GET /platforms` and receives a list of platform base URLs (e.g. `["https://blabsy.example.com", "https://pictique.example.com", ...]`). +1. **Platform list**: [eVault](/docs/Infrastructure/eVault) calls the [Registry](/docs/Infrastructure/Registry) with `GET /platforms` and receives a list of platform base URLs (e.g. `["https://blabsy.example.com", "https://pictique.example.com", ...]`). 2. **Filter**: The requesting platform is removed from the list. The requestor is identified from the Bearer token's `platform` claim (the platform URL that was certified when the token was issued). URL comparison is normalized so that equivalent URLs are treated as the same. 3. **Delivery**: For each remaining URL, the eVault sends `POST {platformUrl}/api/webhook` with the awareness protocol payload. Each request has a 5-second timeout. Requests are sent in parallel (`Promise.allSettled`); if one fails, others still run, and failures are logged without blocking the mutation. @@ -65,8 +65,8 @@ The body of each webhook request is JSON with the following fields: |-------|-------------| | `id` | MetaEnvelope ID (W3ID). | | `w3id` | Owner eName (eVault owner W3ID). | -| `schemaId` | Ontology/schema UUID (identifies the type of entity and which mapping the platform should use). | -| `data` | The entity payload in the **global ontology** shape (parsed key-value structure). | +| `schemaId` | [Ontology](/docs/Infrastructure/Ontology) schema W3ID (identifies the type of entity and which mapping the platform should use). | +| `data` | The entity payload in the **global ontology** shape (parsed key-value structure). See [eVault](/docs/Infrastructure/eVault) for MetaEnvelope storage. | In the current version of the implementation the entire payload is sent in plain text to any registered platform, so all data is sent to every platform and @@ -99,7 +99,7 @@ Platforms that participate in W3DS must implement an HTTP endpoint that accepts - **Method and path**: `POST /api/webhook` - **Request**: JSON body as described above. -- **Behavior**: The platform should (1) use `schemaId` to find the correct mapping from global ontology to local schema, (2) transform `data` from global to local format (e.g. using the Web3 Adapter's `fromGlobal`), (3) resolve or create the local entity and store the global-ID-to-local-ID mapping, (4) return HTTP 200 on success. +- **Behavior**: The platform should (1) use `schemaId` to find the correct mapping from global ontology to local schema, (2) transform `data` from global to local format (e.g. using the [Web3 Adapter](/docs/Infrastructure/Web3-Adapter#fromglobal)'s `fromGlobal`), (3) resolve or create the local entity and store the global-ID-to-local-ID mapping, (4) return HTTP 200 on success. - **Idempotency**: Implementors are encouraged to treat the same `id` (global ID) as idempotent (create or update the same local entity) so that duplicate or retried deliveries do not create duplicates. For a step-by-step implementation guide, see the [Webhook Controller Guide](/docs/Post%20Platform%20Guide/webhook-controller) in the Post Platform Guide. @@ -114,3 +114,11 @@ The current protocol has limitations which are going to be improved in subseque - **Platform list from Registry**: The set of recipients is whatever the Registry returns for `GET /platforms`. This is a prototype level shortcut and will be phased out. Designing retries, ordering, or delivery guarantees would be natural extension points for a production-grade awareness mechanism. + +## References + +- [eVault](/docs/Infrastructure/eVault) — Webhook delivery and GraphQL API +- [Registry](/docs/Infrastructure/Registry) — Platform list (prototype) +- [Ontology](/docs/Infrastructure/Ontology) — Schema IDs +- [Web3 Adapter](/docs/Infrastructure/Web3-Adapter#fromglobal) — `fromGlobal` and mapping +- [Webhook Controller Guide](/docs/Post%20Platform%20Guide/webhook-controller) — Implementation diff --git a/docs/docs/W3DS Protocol/Signature-Formats.md b/docs/docs/W3DS Protocol/Signature-Formats.md index 318517d4..204e87c3 100644 --- a/docs/docs/W3DS Protocol/Signature-Formats.md +++ b/docs/docs/W3DS Protocol/Signature-Formats.md @@ -4,11 +4,11 @@ sidebar_position: 3 # Signature Formats -This document explains the signature formats used in the eID wallet and how to verify signatures using public keys from eVault. +This document explains the signature formats used in the [eID wallet](/docs/Infrastructure/eID-Wallet) and how to verify signatures using public keys from [eVault](/docs/Infrastructure/eVault). ## Overview -Signatures in the eID wallet are created using ECDSA P-256 with SHA-256 hashing. The signature format varies depending on whether a hardware or software key is used. All signatures can be verified using the public keys stored in eVault. +Signatures in the eID wallet are created using ECDSA P-256 with SHA-256 hashing. The signature format varies depending on whether a hardware or software key is used. All signatures can be verified using the public keys stored in [eVault](/docs/Infrastructure/eVault). ## Signature Formats @@ -84,7 +84,7 @@ The public key can be in two formats: ### Verification Flow -The verification process retrieves the public key from eVault and verifies the signature: +The verification process retrieves the public key from [eVault](/docs/Infrastructure/eVault) and verifies the signature (see [Registry](/docs/Infrastructure/Registry) for resolution and JWKS): ```mermaid sequenceDiagram @@ -321,12 +321,12 @@ The provisioning process creates an eVault tied to your generated public key: - Receive JWT token containing entropy value 2. **Generate Namespace** - - Create a UUID v4 for the namespace identifier + - Create a unique identifier for the namespace 3. **Provision eVault** - Send POST request to Provisioner `/provision` endpoint with: - `registryEntropy`: JWT token from step 1 - - `namespace`: UUID from step 2 + - `namespace`: Identifier from step 2 - `verificationId`: Verification code (demo code or your verification ID) - `publicKey`: Multibase-encoded public key from key generation - Provisioner validates entropy, generates W3ID, creates eVault, stores public key, and requests key binding certificate from Registry @@ -567,6 +567,11 @@ This workflow enables full desktop-based development and testing of authenticati ## References +- [eID Wallet](/docs/Infrastructure/eID-Wallet) — Key management and signature creation +- [eVault](/docs/Infrastructure/eVault) — Public keys and key binding certificates +- [Registry](/docs/Infrastructure/Registry) — JWKS for JWT verification +- [Signing](/docs/W3DS%20Protocol/Signing) — Verification flow +- [Authentication](/docs/W3DS%20Protocol/Authentication) — How platforms verify signatures - [ECDSA Specification](https://tools.ietf.org/html/rfc6979) - [Multibase Encoding](https://github.com/multiformats/multibase) - [JWT Specification](https://tools.ietf.org/html/rfc7519) diff --git a/docs/docs/W3DS Protocol/Signing.md b/docs/docs/W3DS Protocol/Signing.md index 3e511863..1713c54d 100644 --- a/docs/docs/W3DS Protocol/Signing.md +++ b/docs/docs/W3DS Protocol/Signing.md @@ -57,23 +57,23 @@ sequenceDiagram The platform creates a signing session with: -1. **Generate Session ID**: Create a unique UUID for the signing session +1. **Generate Session ID**: Create a unique session ID for the signing session 2. **Prepare Data**: Create a JSON object containing: - `message`: Human-readable description of what's being signed - - `sessionId`: The session UUID + - `sessionId`: The session ID - Any additional context-specific data 3. **Encode Data**: Base64-encode the JSON string 4. **Build w3ds://sign URI**: Create URI with format: ```text w3ds://sign?session={sessionId}&data={base64Data}&redirect_uri={encodedRedirectUri} ``` - - `session`: The session UUID + - `session`: The session ID - `data`: Base64-encoded JSON containing the message and context - `redirect_uri`: URL-encoded endpoint where the eID wallet will POST the signed payload (this is the callback URL) 5. **Store Session**: Store session in memory/database with expiration (typically 15 minutes) **Implementation Requirements**: -- Generate UUID v4 for session ID +- Generate a cryptographically secure random session ID - Create JSON object with message and context data - Base64-encode the JSON string - URL-encode the redirect_uri parameter @@ -96,7 +96,7 @@ const qrData = `w3ds://sign?session=${sessionId}&data=${base64Data}&redirect_uri ``` **Language-Agnostic Implementation**: -- Use any UUID library to generate session ID (uuid in Node.js, uuid in Python, google/uuid in Go, etc.) +- Use any library to generate a unique session ID (e.g. crypto.randomUUID in Node.js, uuid in Python, google/uuid in Go) - Use standard JSON serialization - Use standard base64 encoding (base64 in Python, base64 in Go, Buffer in Node.js, etc.) - Use URL encoding for the redirect_uri parameter @@ -167,7 +167,7 @@ Content-Type: application/json ``` **Field Descriptions**: -- `sessionId`: The session UUID from the signing request +- `sessionId`: The session ID from the signing request - `signature`: The base64 or multibase-encoded signature of the session ID - `w3id`: The user's eName (W3ID) - `message`: The session ID that was signed (for verification) @@ -240,7 +240,7 @@ async handleSignedPayload(req: Request, res: Response) { 1. **Session Expiration**: Sessions should expire after a reasonable time (15 minutes recommended) 2. **One-Time Use**: Each session ID should only be used once 3. **User Verification**: Verify that the signing user matches the expected user -4. **Signature Verification**: Always verify signatures using eVault before processing +4. **Signature Verification**: Always verify signatures using [eVault](/docs/Infrastructure/eVault) before processing 5. **Payload Validation**: Ensure the signed message (session ID) matches the stored session ### Use Cases @@ -258,7 +258,7 @@ Signature verification is a multi-step process that platforms must implement. Th ### Overview The verification process: -1. Resolve eVault URL from Registry using eName +1. Resolve [eVault](/docs/Infrastructure/eVault) URL from [Registry](/docs/Infrastructure/Registry) using eName 2. Fetch key binding certificates from eVault 3. Verify JWT certificates using Registry's public keys 4. Extract public keys from verified certificates @@ -266,7 +266,7 @@ The verification process: ### Step 1: Resolve eVault URL -Make an HTTP GET request to the Registry service: +Make an HTTP GET request to the [Registry](/docs/Infrastructure/Registry) service: **Request**: ```http @@ -284,7 +284,7 @@ GET {registryBaseUrl}/resolve?w3id=@user-a.w3id ### Step 2: Get Key Binding Certificates -Make an HTTP GET request to the eVault's `/whois` endpoint: +Make an HTTP GET request to the [eVault](/docs/Infrastructure/eVault)'s `/whois` endpoint: **Request**: ```http @@ -504,6 +504,9 @@ To implement signature verification, you'll need: ## References +- [eVault](/docs/Infrastructure/eVault) — Public keys and `/whois` +- [Registry](/docs/Infrastructure/Registry) — W3ID resolution and JWKS +- [eID Wallet](/docs/Infrastructure/eID-Wallet) — Key management and signing - [Authentication](/docs/W3DS%20Protocol/Authentication) - How authentication uses signatures - [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Detailed signature format documentation - [ECDSA Specification](https://tools.ietf.org/html/rfc6979) - ECDSA algorithm details diff --git a/docs/docs/W3DS Protocol/_category_.json b/docs/docs/W3DS Protocol/_category_.json index bcb835f0..ea246a7c 100644 --- a/docs/docs/W3DS Protocol/_category_.json +++ b/docs/docs/W3DS Protocol/_category_.json @@ -1,7 +1,4 @@ { "label": "W3DS Protocol", - "position": 4, - "link": { - "type": "generated-index" - } + "position": 4 } \ No newline at end of file diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index c4f58482..00fe1561 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -7,7 +7,7 @@ import type * as Preset from '@docusaurus/preset-classic'; const config: Config = { title: 'W3DS Documentation', tagline: 'Documentation for Web 3 Data Spaces', - favicon: 'img/favicon.ico', + favicon: 'img/w3dslogo.svg', // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future future: { @@ -20,16 +20,12 @@ const config: Config = { themes: ['@docusaurus/theme-mermaid'], - // Set the production url of your site here - url: 'https://MetaState-Prototype-Project.github.io', - // Set the // pathname under which your site is served - // For GitHub pages deployment, it is often '//' - baseUrl: '/prototype', + // Production URL: hosted at docs.w3ds.metastate.foundation + url: 'https://docs.w3ds.metastate.foundation', + baseUrl: '/', - // GitHub pages deployment config. - // If you aren't using GitHub pages, you don't need these. - organizationName: 'MetaState-Prototype-Project', // Usually your GitHub org/user name. - projectName: 'MetaState-Prototype-Project.github.io', // Usually your repo name. + organizationName: 'MetaState-Prototype-Project', + projectName: 'metastate', trailingSlash: false, onBrokenLinks: 'throw', @@ -48,18 +44,14 @@ const config: Config = { { docs: { sidebarPath: './sidebars.ts', - // Please change this to your repo. - // Remove this to remove the "edit this page" links. - editUrl: - 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', + editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/', }, } satisfies Preset.Options, ], ], themeConfig: { - // Replace with your project's social card - image: 'img/docusaurus-social-card.jpg', + image: 'img/w3dslogo.svg', colorMode: { respectPrefersColorScheme: true, }, @@ -73,7 +65,7 @@ const config: Config = { type: 'docSidebar', sidebarId: 'tutorialSidebar', position: 'left', - label: 'Tutorial', + label: 'Docs', }, { href: 'https://github.com/MetaState-Prototype-Project/prototype', @@ -89,13 +81,25 @@ const config: Config = { title: 'Docs', items: [ { - label: 'Documentaion', + label: 'Getting Started', to: '/docs/Getting%20Started/getting-started', }, + { + label: 'W3DS Basics', + to: '/docs/W3DS%20Basics/getting-started', + }, + { + label: 'Infrastructure', + to: '/docs/Infrastructure/eVault', + }, + { + label: 'Links', + to: '/docs/W3DS%20Basics/Links', + }, ], }, ], - copyright: `Copyright © ${new Date().getFullYear()} Stichting MetasState Foundation. Built with Docusaurus.`, + copyright: `Copyright © ${new Date().getFullYear()} Stichting MetaState Foundation.`, }, prism: { theme: prismThemes.github, diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx index 6965e534..3319ad71 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -1,21 +1,25 @@ import { useEffect, type ReactNode } from 'react'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; import Layout from '@theme/Layout'; -import { useHistory } from "@docusaurus/router" +import { useHistory, useLocation } from '@docusaurus/router'; export default function Home(): ReactNode { const { siteConfig } = useDocusaurusContext(); const history = useHistory(); - + const location = useLocation(); useEffect(() => { - history.push("/prototype/docs/Getting Started/getting-started") - }, []) + const raw = siteConfig.baseUrl ?? '/'; + const baseUrl = raw.endsWith('/') ? raw : `${raw}/`; + const rootPathname = baseUrl === '/' ? '/' : baseUrl.replace(/\/$/, ''); + if (location.pathname !== rootPathname && location.pathname !== baseUrl) return; + history.replace(`${baseUrl}docs/Getting%20Started/getting-started`); + }, [siteConfig.baseUrl, location.pathname, history]); return ( + title="W3DS Documentation" + description="Documentation for Web 3 Data Spaces — eVault, Registry, Ontology, and the W3DS protocol."> ); }