Skip to content

Commit fe4ce98

Browse files
PatStLouisPatStLouis
committed
rebase
Signed-off-by: Patrick St-Louis <[email protected]>
2 parents 37498b0 + e8a30fa commit fe4ce98

File tree

16 files changed

+2087
-77
lines changed

16 files changed

+2087
-77
lines changed

‎.github/workflows/pages.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Documentation
2+
on:
3+
push:
4+
branches:
5+
- main
6+
permissions:
7+
contents: read
8+
pages: write
9+
id-token: write
10+
jobs:
11+
deploy:
12+
environment:
13+
name: github-pages
14+
url: ${{ steps.deployment.outputs.page_url }}
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/configure-pages@v5
18+
- uses: actions/checkout@v5
19+
- uses: actions/setup-python@v5
20+
with:
21+
python-version: 3.x
22+
- run: pip install zensical
23+
- run: zensical build --clean
24+
- uses: actions/upload-pages-artifact@v4
25+
with:
26+
path: site
27+
- uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 18 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -4,57 +4,8 @@ A Web Server component for a DID WebVH implementation built with FastAPI.
44

55
**DID WebVH Specification**: [https://identity.foundation/didwebvh](https://identity.foundation/didwebvh)
66

7-
## Abstract
8-
9-
This server enables controllers to deposit their DID documents, DID logs, and attested resources (including AnonCreds objects) in a secure, policy-driven environment.
10-
11-
By separating the storage of verification material from the signing operations, the architecture provides:
12-
- **Security**: Signing material isolation
13-
- **Governance**: Configurable policies for witness requirements, endorsement, portability, and more
14-
- **Verifiability**: Cryptographic proofs and append-only history
15-
- **Interoperability**: Support for AnonCreds, W3C Verifiable Credentials, and DID Attested Resources
16-
17-
## How It Works
18-
19-
The DID WebVH Server follows a policy-driven approach where controllers request DID paths, receive policy parameters, and submit signed log entries for verification and publication.
20-
21-
### Key Workflow
22-
23-
1. **Controller requests a DID path** from the server
24-
2. **Server returns policy-driven parameters** that must be used
25-
3. **Controller creates and signs** the initial log entry
26-
4. **Controller obtains witness signatures** (if required by policy)
27-
5. **Controller submits** the log entry with witness proofs
28-
6. **Server verifies and publishes** the DID document and history
29-
30-
### Registering a New DID
31-
32-
```mermaid
33-
sequenceDiagram
34-
participant WebVH Server
35-
participant Controller
36-
participant Witness
37-
Controller->>WebVH Server: Request a did path.
38-
WebVH Server->>Controller: Provide log input document with policy.
39-
Controller->>Controller: Create and sign initial log entry.
40-
Controller->>Witness: Request witness signature if required.
41-
Controller->>WebVH Server: Send initial log entry and did witness signature.
42-
WebVH Server->>WebVH Server: Verify and publish DID.
43-
```
44-
45-
## Features
46-
47-
- **DID Management**: Create, resolve, and manage DIDs with WebVH method
48-
- **Attested Resources**: Upload and manage AnonCreds objects, schemas, credential definitions
49-
- **Witness Registry**: Manage known witness services and their invitation URLs
50-
- **Policy Enforcement**: Configurable policies for witness, endorsement, portability, prerotation
51-
- **Web Explorer**: Interactive UI for browsing DIDs, resources, and witness network
52-
- **Multiple Storage**: SQLite (default) or PostgreSQL backends
53-
547
## Quick Start
558

56-
See [`server/README.md`](server/README.md) for detailed setup instructions.
57-
589
```bash
5910
# Install dependencies
6011
cd server
@@ -68,41 +19,31 @@ cp env.example .env
6819
uv run python main.py
6920
```
7021

22+
The server will be available at `http://localhost:8000` with:
23+
- **API Documentation**: `http://localhost:8000/docs` (Swagger UI)
24+
- **Web Explorer**: `http://localhost:8000/api/explorer`
25+
7126
## Documentation
7227

73-
📚 **For complete documentation, see the [User Manual](docs/content/index.md)**
28+
📚 **Complete documentation is available in the [User Manual](docs/index.md)**
7429

75-
The user manual includes:
76-
- **Getting Started**: Installation and setup
77-
- **Configuration**: All environment variables and settings
78-
- **API Endpoints**: Complete API reference
79-
- **Protocols**: Detailed protocol flows (Connecting to Witness, Requesting DID Path, Creating Log Entry)
80-
- **Roles**: Admin, Witness, Controller, and Watcher responsibilities
81-
- **Admin Operations**: Managing witnesses and policies
82-
- **DID Operations**: Creating, updating, and resolving DIDs
83-
- **AnonCreds**: Publishing and resolving AnonCreds objects
84-
- **Examples**: Practical use cases
30+
To view the documentation locally:
8531

86-
## Additional Resources
32+
```bash
33+
# Install Zensical
34+
pip install zensical
8735

88-
- **[Server README](server/README.md)**: Quick setup guide for the server
89-
- **Interactive API Docs**: Swagger UI available at `/docs` when server is running
90-
- **Demo**: See the `demo/` directory for example usage
36+
# Start the documentation server
37+
zensical serve
38+
```
9139

92-
## Project Structure
40+
The documentation will be available at `http://localhost:8000` (or the port specified in `zensical.toml`).
9341

94-
```
95-
didwebvh-server-py/
96-
├── server/ # FastAPI server application
97-
│ ├── app/
98-
│ │ ├── routers/ # API route handlers
99-
│ │ ├── plugins/ # Core plugins
100-
│ │ └── templates/ # Web explorer UI
101-
│ └── env.example # Environment configuration template
102-
├── docs/ # User manual and documentation
103-
└── demo/ # Demonstration examples
104-
```
42+
## Additional Resources
43+
44+
- **[Server README](server/README.md)**: Quick setup guide
45+
- **Demo**: See the `demo/` directory for load testing and examples
10546

10647
## License
10748

108-
Apache License 2.0
49+
Apache License 2.0

‎docs/.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Zensical build output (HTML files and directories)
2+
*.html
3+
!content/**/*.html
4+
assets/
5+
.zensical
6+
7+
# Python cache
8+
__pycache__
9+
*.pyc
10+
11+
# Keep source content and README
12+
!content/
13+
!README.md
14+

‎docs/about.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# About
2+
3+
The DID WebVH Server is a FastAPI-based server for managing Decentralized Identifiers (DIDs) using the WebVH (Web Verifiable History) method. It provides endpoints for creating, updating, and resolving DIDs, as well as managing witness services and server policies.
4+
5+
## What is DID WebVH?
6+
7+
**DID WebVH** (Decentralized Identifier Web Verifiable History) is a DID method specification that provides a secure, policy-driven approach to managing Decentralized Identifiers on the web.
8+
9+
This server implementation enables controllers to deposit their DID documents, DID logs, and attested resources (including AnonCreds objects) in a secure, policy-driven environment.
10+
11+
## Key Benefits
12+
13+
### 🔒 Security
14+
15+
By separating the storage of verification material from the signing operations, the architecture provides:
16+
17+
- **Signing Material Isolation**: Signing keys remain with controllers and witnesses, not on the server
18+
- **Cryptographic Proofs**: All operations are cryptographically verified
19+
- **Append-Only History**: Immutable log entries ensure verifiable history
20+
21+
### ⚖️ Governance
22+
23+
Configurable policies allow you to control:
24+
25+
- **Witness Requirements**: Require witness signatures for DID operations
26+
- **Endorsement Policies**: Control which resources and credentials need endorsement
27+
- **Portability**: Enable or disable DID portability features
28+
- **Prerotation**: Configure key rotation policies
29+
30+
### 📜 Verifiability
31+
32+
- **Cryptographic Verification**: All log entries are cryptographically signed
33+
- **Append-Only Logs**: Immutable history ensures auditability
34+
- **Version Control**: Track all changes to DID documents over time
35+
36+
### 🔗 Interoperability
37+
38+
Full support for:
39+
40+
- **AnonCreds**: Publish and resolve AnonCreds schemas and credential definitions
41+
- **W3C Verifiable Credentials**: Support for standard VC formats
42+
- **DID Attested Resources**: Manage any type of attested resource
43+
44+
## Architecture
45+
46+
The DID WebVH Server follows a policy-driven workflow:
47+
48+
```mermaid
49+
sequenceDiagram
50+
participant Controller
51+
participant Server
52+
participant Witness
53+
54+
Controller->>Server: Request DID path
55+
Server->>Controller: Return policy parameters
56+
Controller->>Controller: Create and sign log entry
57+
Controller->>Witness: Request witness signature (if required)
58+
Witness->>Controller: Provide witness signature
59+
Controller->>Server: Submit log entry with proofs
60+
Server->>Server: Verify and publish DID
61+
```
62+
63+
## Components
64+
65+
### Server
66+
67+
The server component is responsible for:
68+
69+
- **Policy Management**: Enforcing configurable policies for DID operations
70+
- **Verification**: Verifying signatures and proofs from controllers and witnesses
71+
- **Storage**: Hosting DID documents (`did.json`) and log files (`did.jsonl`)
72+
- **Resource Management**: Managing attested resources and their metadata
73+
74+
### Controller
75+
76+
The controller role:
77+
78+
- **Creates DIDs**: Requests DID paths and creates initial log entries
79+
- **Updates DIDs**: Submits signed log entries for updates
80+
- **Manages Resources**: Uploads and manages attested resources
81+
- **Interacts with Witnesses**: Requests witness signatures when required
82+
83+
### Witness
84+
85+
The witness role:
86+
87+
- **Signs Operations**: Provides cryptographic signatures for DID operations
88+
- **Endorses Resources**: Endorses attested resources and verifiable credentials
89+
- **Verifies Requests**: Validates controller requests before signing
90+
91+
### Watcher
92+
93+
The watcher role (optional):
94+
95+
- **Monitors Changes**: Watches for DID document and log changes
96+
- **Receives Notifications**: Gets notified of updates and new resources
97+
- **Audit Trail**: Maintains audit logs of all operations
98+
99+
## Key Features
100+
101+
- **DID Creation and Management**: Create and manage DIDs with verifiable history
102+
- **Witness Services**: Integrate with witness services for DID attestation
103+
- **Policy Enforcement**: Configurable policies for witness requirements, portability, prerotation, and more
104+
- **Admin API**: Administrative endpoints for managing witnesses and policies
105+
- **Resource Management**: Store and serve attested resources bound to DIDs
106+
- **Web Explorer**: Interactive web interface for browsing DIDs, resources, and witness network
107+
- **AnonCreds Support**: Publish and resolve AnonCreds objects as Attested Resources
108+
109+
## Technology Stack
110+
111+
- **Framework**: FastAPI (Python)
112+
- **Database**: SQLite or PostgreSQL
113+
- **Storage**: Configurable storage backends
114+
- **API**: RESTful API with OpenAPI documentation
115+
- **Web UI**: Modern web explorer interface
116+
117+
## Specification
118+
119+
This server implements the [DID WebVH Specification](https://identity.foundation/didwebvh) maintained by the Decentralized Identity Foundation (DIF).
120+
121+
## License
122+
123+
This project is open source and available under the Apache 2.0 License.
124+
125+
## Community
126+
127+
- **Repository**: [GitHub](https://github.com/decentralized-identity/didwebvh-server-py)
128+
- **Issues**: [GitHub Issues](https://github.com/decentralized-identity/didwebvh-server-py/issues)
129+
- **Discussions**: [GitHub Discussions](https://github.com/decentralized-identity/didwebvh-server-py/discussions)
130+
131+
## Getting Started
132+
133+
Ready to get started? Check out our [Getting Started Guide](getting-started.md) or explore the [User Guide](user-manual.md) for comprehensive documentation.
134+

‎docs/admin-operations.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Admin Operations
2+
3+
Admin endpoints require API key authentication via the `x-api-key` header.
4+
5+
## Witness Management
6+
7+
### Add Witness
8+
9+
- **POST** `/api/admin/witnesses`
10+
- **Headers**: `x-api-key: <WEBVH_ADMIN_API_KEY>`
11+
- **Body**:
12+
```json
13+
{
14+
"id": "did:key:z6Mk...",
15+
"label": "Example Witness Service",
16+
"invitationUrl": "https://witness.example.com/oob-invite?oob=<base64_encoded_invitation>"
17+
}
18+
```
19+
- Decodes the invitation, stores it, and creates a short URL in the registry
20+
21+
### Remove Witness
22+
23+
- **DELETE** `/api/admin/witnesses/{multikey}`
24+
- **Headers**: `x-api-key: <WEBVH_ADMIN_API_KEY>`
25+
- Removes a witness from the registry
26+
27+
## Policy Management
28+
29+
### Get Parameters
30+
31+
- **GET** `/api/admin/parameters`
32+
- **Headers**: `x-api-key: <WEBVH_ADMIN_API_KEY>`
33+
- Returns the parameters generated from the active policy
34+
- Includes witness configuration, method version, and other policy-driven settings
35+
36+
## Witness Management
37+
38+
### Automatic Registration
39+
40+
If both `WEBVH_WITNESS_ID` and `WEBVH_WITNESS_INVITATION` are set, the server will automatically:
41+
42+
1. Decode the invitation from the URL
43+
2. Store the invitation using the witness DID as the key
44+
3. Update the witness registry with a short URL (`https://{DOMAIN}/api/invitations?_oobid={witness_key}`)
45+
4. Update the invitation if it changes on restart
46+
47+
### Invitation Lookup
48+
49+
Witness invitations can be retrieved via the root endpoint:
50+
51+
- **GET** `/api/invitations?_oobid={witness_key}`
52+
- Returns the stored invitation as JSON
53+
- The `witness_key` is the multikey portion of the `did:key` identifier
54+
55+
### Short URLs
56+
57+
The server generates short URLs for witness invitations in the format:
58+
```
59+
https://{DOMAIN}/api/invitations?_oobid={witness_key}
60+
```
61+
62+
These URLs are:
63+
- Stored in the witness registry as `serviceEndpoint`
64+
- Included in the server's DID document under `WitnessInvitation` services
65+
- Resolvable via the root endpoint to return the full invitation JSON
66+
67+
68+
69+
70+

0 commit comments

Comments
 (0)