{"id":19571602,"url":"https://github.com/block-core/blockcore-vault","last_synced_at":"2025-04-27T03:32:24.840Z","repository":{"id":40943603,"uuid":"361826579","full_name":"block-core/blockcore-vault","owner":"block-core","description":"Verifiable Credential Server for Web5.","archived":false,"fork":false,"pushed_at":"2022-12-17T00:02:51.000Z","size":5431,"stargazers_count":12,"open_issues_count":8,"forks_count":15,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-19T03:24:12.936Z","etag":null,"topics":["web3","web5"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/block-core.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-04-26T16:53:52.000Z","updated_at":"2024-04-07T18:46:22.000Z","dependencies_parsed_at":"2023-01-29T16:30:17.061Z","dependency_job_id":null,"html_url":"https://github.com/block-core/blockcore-vault","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block-core%2Fblockcore-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block-core%2Fblockcore-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block-core%2Fblockcore-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block-core%2Fblockcore-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/block-core","download_url":"https://codeload.github.com/block-core/blockcore-vault/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251085145,"owners_count":21533821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["web3","web5"],"created_at":"2024-11-11T06:19:26.625Z","updated_at":"2025-04-27T03:32:23.098Z","avatar_url":"https://github.com/block-core.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://avatars3.githubusercontent.com/u/53176002?s=200\u0026v=4\" height=\"100\" alt=\"Blockcore\" /\u003e\n  \u003c/p\u003e\n  \u003ch3 align=\"center\"\u003e\n    About Blockcore Vault\n  \u003c/h3\u003e\n  \u003cp align=\"center\"\u003e\n    Verifiable Credential Server\n  \u003c/p\u003e\n\u003c/p\u003e\n\n# Blockcore Vault\n\nServer for Verifiable Credentials ([VC](https://www.w3.org/TR/vc-data-model/)) managed by Decentralized Identifiers ([DID](https://www.w3.org/TR/did-core/)).\n\n## What does Blockcore Vault do?\n\nThis software provides a generic interface for storing and serving VCs in a manner that is easy to use.\n\n![](/docs/blockcore-vault.png)\n\n## Setup\n\nYou must configure your instance of Blockcore Vault using the environment variables. An sample .env.sample is provided, rename this to .env only.\n\n### Environment variables\n\n**ADMIN**: This is important to set and required for authentication (login) to work.\n\n**JWT_KEY**: This is important to change, generate your own new secret before you start using Blockcore Vault.\n\n## What about Decentralized Web Nodes?\n\nDWN are the future for VC storage, but the specification is currently only in `draft` state. In preparation for a fully fledge DWN specification and implementations, the Blockcore Vault is an alternative with a simpler API interface.\n\nSource code: [blockcore-dwn](https://github.com/block-core/blockcore-dwn)   \nSpecification: [decentralized-web-node](https://identity.foundation/decentralized-web-node/spec/)\n\n## What is Web5?\n\nLearn more: [https://developer.tbd.website/projects/web5/](https://developer.tbd.website/projects/web5/)\n\nBlockcore Vault is a work-in-progress and is focused on delivering implementation of open standard specifications developed by the Decentralized Identity Foundation ([DIF](https://github.com/decentralized-identity)).\n\nThe various standards are currently in development, so the Blockcore Vault will continue to be in development and change according to the specifications.\n\nBlockcore Vault is not a reference implementation of the standards, and we have limited development resources available for implementation, so we will implement parts of the standards. We strive towards interopability with other implementations, but can't do full standard implementations without funding and support.\n\nTo learn more about the definitions and concepts, make sure you check out the [Decentralized Identity FAQ](https://identity.foundation/faq/).\n\n## All Your Devices\n\nBlockcore Vault will in the future be available for many devices, and all your data will flow with you across those devices. Your diplomas, tickets, receipts, messages and everything else of important data in your life, will be accessible from Blockcore Vault (or Blockcore DWN) on all your digital devices. All your data will seamlessly synchronize between your devices.\n\nFor sharing with friends, family and the public, you can rent or host your own Blockcore Vault Server in the cloud, or at home. This will allow you to share with others, data that is always accessible and online, even when you are not.\n\n## Setup\n\nTo set up the application, first clone the repo. Then, install the dependencies by running npm:\n\n```sh\nnpm run setup\n```\n\n## Build and Serve\n\nYou can easily build and serve the app in production mode:\n\n```sh\nnpm run static\n```\n\nThis will run both `api` and `ui` build and hosting in parallel, there are no auto-reloads.\n\nYou can access the UI:\n\n[http://localhost:4350](http://localhost:4350)\n\n## Run and Reload\n\n```sh\nnpm start\n```\n\nThis will perform a static build of the API, serve that API and then host an dynamic instance of the UI with auto-reload.\n\nBoth API and UI is hosted on different ports:\n\nUI: [http://localhost:4202](http://localhost:4202)   \nAPI: [http://localhost:4350](http://localhost:4350)\n\n## Build and Deploy\n\nBuilding the production code and prepare it for deployment can be done using:\n\n```sh\nnpm run build\n```\n\nThis will build both the `api` (Node.js) and the `ui` (Angular) and copy the output from the `ui` into the API. This allows both the API and UI to be hosted on same web server.\n\n## Docker\n\nThe `dockerfile` will take pre-built output and copy that into the image.\n\n## Making Requests\n\nThe server has many different endpoints:\n\n- `GET /.well-known/did.json`\u0026mdash;Returns the DID of the server.\n- `GET /.well-known/did-configuration.json`\u0026mdash;Returns the DID Configuration of the server.\n- `GET /.well-known/vault-configuration.json`\u0026mdash;Returns the Vault Configuration of the server\n\n- `GET /`\u0026mdash;Returns all registered vaults.\n- `POST /vault`\u0026mdash;Adds another vault as a trusted vault to this vault.\n- `DELETE /vault`\u0026mdash;Removes another vault as a trusted vault on this vault.\n\nThe GET endpoint can be viewed simply by navigating to `http://localhost:3000`. You should see \"Welcome to Blockcore Vault\".\n\n## Controllers\n\n### Vault (\"Confidential Storage\") API\n\nAllows CRUD operations over `DataVaultConfiguration`, allows a vault to have multiple parties that are allowed to post data to it.\n\nWhen a new `DataVaultConfiguration` is submitted, the `storage provider` can run the Blockcore Vault software in a public and free mode or in manual approval mode, where\nindividual vaults must be approved before they can be used by the `data vault controller` or `storage agent`.\n\nExample data vault URL:\n\nhttp://localhost:3000/data/z4sRgBJJLnYy\n\nAll operations on the Vault requires requests to be signed by the keys specified in the DID Document. If the software is unable to resolve the DID Document, then verification will fail and storage will not be possible.\n\nReplication configuration is part of the vault creation operation.\n\nVault type should be part of the vault creation operation. Vault types could be encrypted, unencrypted, immutable, mutable, etc.\n\n### Server (\"Management\") API\n\nAllows a storage provider (administrator) to register and manage trusted Blockcore Vault instances to syncronize data with.\n\n### .well-known API\n\nAllows for public discovery using known URLs to find DID, DID Configuration and Vault Configuration.\n\n### Statistics (\"Stats\") API\n\nUsed to retrieve various metrics recorded by the Blockcore Vault instance. This can be used to analyze the usage performed by various vault contributors.\n\nData from this API is used to enforce throtteling rules that an administrator applies to individual vaults.\n\n# Using Blockcore Vault\n\nAfter launching the Blockcore Vault instance, you can use the Blockcore Vault UI to manage your Blockcore Vault instance(s).\n\nThe first task to configure a Blockcore Vault, is to create an decentralized identity (DID) and publish the DID Document that describes your Vault to\nan public DID registry.\n\nAfter you have initialized your Blockcore Vault, you can start adding communication with other trusted Vaults to become part of a network of Vault instances.\n\nYou can run your own network of Vault instances, or join other networks.\n\nWhen you connect with other Vault instances, you will always sync the full repository of DID Documents that exists on the other Vaults.\n\nOther data will be synced based upon the configuration you setup on your Blockcore Vault UI.\n\n## Register a trusted Vault\n\nTODO: When you want to add trust between two Blockcore Vault, you will from the Vault UI perform queries against the URL you provide.\n\n1. The web UI will query the .well-known/did-configuration.json of the server you provided.\n2. The web UI will run call with a universal resolver that will attempt to resolve the DID Document based on the DID provided in the did-configuration.json.\n3. Verification between the domain you supplied and the DID Document is performed.\n4. Name of the Vault is retrieved from the .well-known/vault-configuration.json. It also has the `dataVaultCreationService` URL which might be used, or the `serviceEndpoint` of the `EncryptedDataVault` entry in the DID Document will be used. Could maybe used either or, depending on what is available. Perhaps prefer the service entry in DID Document, and fallback to vault-configuration.json which is Blockcore custom specification.\n5. An initiation request to be sent to the Vault is created and signed in the web UI with the private key never leaving the local browser. The initiation request is sent and stored on the users own Vault, and is sent to the external Vault when the server is registered.\n6. The users Vault will keep checking at intervals the approval status of the initiation request.\n7. Upon approval (which can be automatic depending on the Vault being connected with) the Vault will open up Web Socket connection, perform authentication based on the key specified in its own DID Document.\n8. Upon valid authentication, syncronization will start.\n\nCURRENT: Currently the implementation of this is simplified and without any authentication or approval process.\n\n## Data Sync\n\nWhen an vault adds another vault, that becomes a client-server relationship. There is not a \"two-way\" relationship, where the server opens connection or performs data sync operations.\n\nWhen the client vault connects up to a server vault (which must be accessible through firewall if on public network, client vault can be behind NAT/firewall), it will initially publish all local events, if there are any.\n\nNext step is to start download events from the server. If there is no previous state stored, sync will happen from zero.\n\nThe server does not keep track of sync status of the connected clients. When the client is finished with sync, it will register itself into the \"new data room\" on Web Socket to be signaled to query for new data.\n\nAll connections must be authenticated (to be implemented) to perform operations on the events API.\n\n## Restrictions\n\nWhen a Vault has registered an outbound (client/server) relationship, the target Vault cannot register a connection back to the same Vault. This is a limitation in the software and the software should avoid such circular connections.\n\nTo setup a resilient network of Blockcore Vault instances, you need at minimum 3 instances.\n\nVault #1 \u003e Vault #2 \u003e Vault #3 \u003e Vault #1.\n\nWhenever an event enters any of these vaults, it will be immediately delivered to both outgoing and incoming connections with a signal over Web Sockets. This ensures if there is some issues or drop between #3 and #1, then #1 will still receive the event from #2.\n\nThe next level of resilience, is having a total of #5 public vault instances. With 5 instances, each of them can have two outgoing and two incoming connections.\n\nIn both of these scenarios, there can be any number of non-public and incoming-only instances of Vault running and receiving data.\n\nIt is of course possible to run just a single vault instance, or a single public instance that only have clients connected.\n\nUpon registration of a trusted vault, the user can decide if a full sync should be performed. By default a full sync is only done on the first connection, not on secondary. If there are two distinct network of vault that should be joint together, this option is useful to ensure all data exists in both networks (and the vaults that belongs to them). Essentially making the two networks into one.\n\nIf a client vault receives an event, it will forward that to all registered and connected server vaults.\n\n# Vocabulary\n\n- `Vault` - An instance of the Blockcore Vault software.\n- `VerifiableDataRegistry` - Verifiable Data Registry (VDR), the Blockcore Vault software is an implementation of an VDR.\n- `Data Vault` - An registered store of data that is hosted on Blockcore Vault software.\n- `DID` - Decentralized identity.\n- `DID Document` - A document that describes keys and other information about an DID Subject.\n- `DID Resolver` - A library / code that allows lookup of DID Documents against an \"DID Registry\"/\"DID Hub\".\n- `VC` - Verifiable Credentials, a signed JSON-document.\n\n# TODO\n\n## Worker Threads\n\nInvestigate if we should Worker Threads for data sync between Vaults. We should consider spawning a seperate thread pr. connected Vault, so that it won't affect the main thread.\n\nPerformance testing is important to figure out if this has any affect or not.\n\nhttps://nodejs.org/api/worker_threads.html\n\nhttps://github.com/uNetworking/uWebSockets.js/blob/master/examples/WorkerThreads.js\n\nImplement the .didState when requiring payments / attestation of submitted DID Documents: https://identity.foundation/did-registration/\n\nDID Implementation Guide:\nhttps://www.w3.org/TR/did-imp-guide/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock-core%2Fblockcore-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblock-core%2Fblockcore-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock-core%2Fblockcore-vault/lists"}