|
1 | 1 | # DID Web with Verifiable History Server Python |
2 | | -## A Web Server component for a DID WebVH implementation |
3 | 2 |
|
4 | | -This server is built with the FastAPI framework. |
| 3 | +A Web Server component for a DID WebVH implementation built with FastAPI. |
5 | 4 |
|
6 | | -The DID WebVH spec: [https://identity.foundation/didwebvh](https://identity.foundation/didwebvh) |
| 5 | +**DID WebVH Specification**: [https://identity.foundation/didwebvh](https://identity.foundation/didwebvh) |
7 | 6 |
|
8 | | -## Abstract |
| 7 | +## Quick Start |
9 | 8 |
|
10 | | -This server is for issuing clients to deposit their did documents, did logs and other objects. |
11 | | - |
12 | | -Having a seperate server to deposit verification material will ensure that signing material is isolated and provide a more secured architecture. |
13 | | - |
14 | | -This also enables system architects to create rigid governance rules around publishing DID documents and related ressources through endorsment. |
15 | | - |
16 | | -## How it works |
17 | | -*For a demonstration, please see the demo directory* |
| 9 | +```bash |
| 10 | +# Install dependencies |
| 11 | +cd server |
| 12 | +uv sync |
18 | 13 |
|
19 | | -- A controller requests an identifier from the server. |
20 | | -- The server returns a configuration if the requested identifier is available. |
21 | | -- The controller generates a first log entry matching the server policies. |
22 | | -- The controller sends the initial log entry to the server, along with the did witness file if required |
| 14 | +# Copy and configure environment |
| 15 | +cp env.example .env |
| 16 | +# Edit .env with your settings |
23 | 17 |
|
24 | | -### Registering a new DID |
25 | | -```mermaid |
26 | | -sequenceDiagram |
27 | | - participant WebVH Server |
28 | | - participant Controller |
29 | | - participant Witness |
30 | | - Controller->>WebVH Server: Request an identifier namespace. |
31 | | - WebVH Server->>Controller: Provide log input document. |
32 | | - Controller->>Controller: Create and sign initial log entry. |
33 | | - Controller->>Witness: Request witness signature if enabled. |
34 | | - Controller->>WebVH Server: Send initial log entry and did witness file if required. |
35 | | - WebVH Server->>WebVH Server: Verify and publish DID. |
| 18 | +# Run server |
| 19 | +uv run python main.py |
36 | 20 | ``` |
37 | 21 |
|
38 | | -### AnonCreds Objects (AttestedResources) |
39 | | - |
40 | | -An attested resource is a stored resource cryptographically bound to it's location on the web. See the anoncreds document for more information. |
41 | | - |
42 | | -### Setting up policies |
43 | | - |
44 | | -The server is equiped with a configurable policy module. Rule sets can be established to change the server behavior when validating some requests. |
45 | | - |
46 | | -When a rule is enforced, the server will reject any request that doesn't match said policy. Here are the configurable policies: |
47 | | - |
48 | | -#### Known Witnesses Registry |
49 | | - |
50 | | -- WEBVH_KNOWN_WITNESS_KEY: A default known witness key to provision the server. |
51 | | - - ex: `WEBVH_KNOWN_WITNESS_KEY="z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"` |
52 | | - |
53 | | -- WEBVH_KNOWN_WITNESS_REGISTRY: A list of known witnesses is used for validating witness policies. This will be cached every time a witness can't be found. |
54 | | - - ex: `WEBVH_KNOWN_WITNESS_REGISTRY="https://known-witnesses.example.com"` |
55 | | - |
56 | | -#### Attested Resource Endorsement |
57 | | - |
58 | | -- WEBVH_ENDORSEMENT: This will require a known witness proof on any attested resource uploaded or updated. It's up to the witness service to determine which resources to endorse from the controller. |
59 | | - - ex: `WEBVH_ENDORSEMENT="true"` |
60 | | - |
61 | | -#### WebVH Parameters |
62 | | - |
63 | | -The following policy variables can be used to enforce parameters from the did:webvh specification: |
64 | | -- WEBVH_VERSION: Specify a webvh method version to enforce |
65 | | - - ex: `WEBVH_VERSION="1.0"` |
66 | | -- WEBVH_WITNESS: Enforce the use of witness with a minimum threshold of 1. At least 1 witness from the known witness registry will need to be used. |
67 | | - - ex: `WEBVH_WITNESS="true"` |
68 | | -- WEBVH_PORTABILITY: Ensure that portability is enabled. |
69 | | - - ex: `WEBVH_PORTABILITY="true"` |
70 | | -- WEBVH_WATCHER: Request a specific watcher to be included in the watchers array |
71 | | - - ex: `WEBVH_WATCHER=https://watcher.example.com` |
72 | | -- WEBVH_PREROTATION: Enforce the use of prerotation |
73 | | - - ex: `WEBVH_PREROTATION="true"` |
74 | | - |
75 | | -### Exploring the resources |
76 | | - |
77 | | -Have a look at the demo directory for instructions on how to browse the explorer. |
| 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` |
78 | 25 |
|
79 | 26 | ## Documentation |
80 | 27 |
|
81 | | -The documentation is built with [Zensical](https://zensical.org/). To view the documentation locally: |
| 28 | +📚 **Complete documentation is available in the [User Manual](docs/index.md)** |
| 29 | + |
| 30 | +To view the documentation locally: |
82 | 31 |
|
83 | 32 | ```bash |
84 | 33 | # Install Zensical |
85 | 34 | pip install zensical |
86 | 35 |
|
87 | | -# Navigate to the project root (where zensical.toml is located) |
88 | | -cd /path/to/didwebvh-server-py |
89 | | - |
90 | 36 | # Start the documentation server |
91 | 37 | zensical serve |
92 | 38 | ``` |
93 | 39 |
|
94 | 40 | The documentation will be available at `http://localhost:8000` (or the port specified in `zensical.toml`). |
95 | 41 |
|
96 | | -For comprehensive documentation, see the [User Manual](docs/user-manual.md) in the `docs/` directory. |
| 42 | +## Additional Resources |
| 43 | + |
| 44 | +- **[Server README](server/README.md)**: Quick setup guide |
| 45 | +- **Demo**: See the `demo/` directory for load testing and examples |
| 46 | + |
| 47 | +## License |
| 48 | + |
| 49 | +Apache License 2.0 |
0 commit comments