Repository files navigation

Findy Agency is an open-source project for a decentralized identity agency.OP Lab developed it from 2019 to 2024. The project is no longer maintained,but the work will continue with new goals and a new mission.Followthe blog for updates.

• findy-agent
  • About findy-agent -Onboard Binding
  • Get Started
  • Run The Agency
  • Edge Agent On-boarding
  • Agency Network
  • Command-line Interface
  • Agency Architecture
  • Aries Protocol State Machine
  • Missing Features For Production

Findy agency is a high-performing, multi-tenant identity agency for Ariesprotocols. It offers a way to allocate Cloud Agents and control them thru gRPCinterfaces. You can think it like a database service, or SMTP service, but it'sa SSI service. With help of it you can run your DID agents where ever you haveinstalled the Findy Agency. Preferred installation place for it is a host withstatic internet presence.

The root of trust for each CAs is in FIDO2 authenticators. WebAuth serveron-boards new agents and JWT is used for the authorization.

You can use Findy Agency roughly for these purposes:

1. As a multi-tenant service for allocating multiple Cloud Agents whichimplementAries agent-to-agent protocolsand offer SSI interoperability.

2. As aCLI tool to setup an agency and maintain it.You can create steward DID and wallet; or you can import steward fromexisting wallet. For command line use it offers all the same features asindy cli.

3. As a high-performing SDK to implement all types SSI Agents likeholders,issuers andverifiers with any programming language you chose which issupported by gRPC.

The Findy Agency is very fast and it is extremely resource efficient; and ofcourse it's Aries compatible.

Findy Agency is a collection of services (Core - this service,WebAuthn,Findy Vault andWeb Wallet) that provide full SSI agency along with a web wallet for individuals. To start experimenting with Findy Agency we recommend you to start withthe documentation andset up the agency to your localhost environment.

• Documentation
• Instructions for starting agency in Docker containers

You can communicate with your agency by gRPC and it offersaCLI tool as well. More documentation for testing with CLI can be foundhere.

Ubuntu 20.04 is preferred development environment but macOS is also an option.Please make sure that Go and git are both installed and working properly.

Note! Go modules must be on.

We recommend that you first installfindy-wrapper-go and follow its guides tosetup environment and especially installlibindy.

1. Install libindy-dev.

2. Clonefindy-agent (this repo)

3. Install needed Go packages:make deps.

4. Install the command line application:make install

5. Verify the installation:findy-agent version

   It should output similar to:findy-agent version 0.xx.xx

Because indy SDK won't offer proper distribution for OSX, we have written ahelper Bash script to perform installation. Follow these stepsinfindy-wrapper-go repo:

0. InstallHomebrew if it isn't already on your machine.
1. Clone the repo:git clone https://github.com/findy-network/findy-wrapper-go
2. Go to directoryfindy-wrapper-go/scripts/mac-libindy:

   $ cd scripts/mac-libindy

3. Execute the installation script.

   $ ./install.sh

   Or, if you want to change the default installation location, enter it asa first argument for the script.

   $ ./install.sh /my/own/location

4. Follow the instructions of theinstall.sh i.e.source the env.sh whichis generated to installation directory and is in your clipboard after successfulinstallation.

   $ source /usr/local/opt/libindy/env.sh

5. Run the tests to see everything is OK with Go wrapper andlibindy:

   make test

6. Then follow instructions from previous sectionLinux and Ubuntu from step2 to completefindy-agent repo's setup.

The problem solving tip:source env.sh in your dev session.

As said earlier the most convenient way to run Findy Agency is from dockercontainer. Still, it's at least as easy to run from standalone binary if youhave proper environment for it to run i.e.libindy installed.

The following chapters describe how to start an agency with different type ofledgers. Before running the agency you must create steward DID and wallet foryour test network.

To create new steward DID and wallet run the following commands:

$ cd scripts/test$ findy-agent ledger steward create --config create-steward-to-mem-ledger.yaml

Thecreate-steward-to-mem-ledger.yaml includes following data.

pool-name: "FINDY_MEM_LEDGER"seed: "000000000000000000000000Steward1"wallet-name: "sovrin_steward_wallet"wallet-key: "4Vwsj6Qcczmhk2Ak7H5GGvFE1cQCdRtWfW4jchahNUoE"

You can edit it for your purpose. Please note to use samewallet-key in it andthe start script likemem-server script in the same directory.

Memory ledger is available as long as the agency is running but after that datais lost. It's very good for tests and short demos.

1. cd scripts/test
2. ./mem-server

File ledger is a test ledger where ledger data is persistently stored into aJSON file. It's convenient for cases where you don't want to run all ledgernodes on your machine like development.

1. cd scripts/test
2. ./file-server

1. Install and start ledger

2. Create a ledger pool with the namevon

   findy-agent ledger pool create --name="von" --genesis-txn-file="genesis.file"

3. Go toscripts/test directory:cd scripts/test

4. Run the agency tests:./von-network-server

5. Connect to agency with your client or test it with the agency's ping command.Please see the helper scripts in thescripts directory.

All of that can be done with themake scratch as well if the predefined ledgerand steward wallet names are OK. The previous steps were for educationalpurposes. If you want to start the agency fast e.g., on OSX, the Makefileapproach is preferable. Please see the scrips in thetools directory.

Findy-agent serves all types of cloud agents (CA) likeholder,issuer andverifier. Cloud agents must be allocated before they can be used. CAallocation is called on-boarding. In most cases it's done thruWebAuthn serverlikefindy-agent-auth but you can allocate them directly from the agency.

Currently onlyfindy-agent-auth on-boards agents to Findy Agency. Since gRPCAPI you should run both Findy Agency and Findy WebAuthn Service where later isonly used for authentication: register and login. The JWT token is used toaccess allocated CA. Please see more [information].

findy-agent is a multi-tenant identity agency that is capable serve thousands ofagents with one installation, and which can scale horizontally.

The following diagram shows all the components of a typical DID/SSI-basedidentity network. The server rack icon illustrates an agency. There are three inthe picture, but typically there can be as many as needed, and agencies can runin a cluster for horizontal scalability.

In the middle of the picture is the indy ledger. Depending on the installationand the type of the network, it can be a public ledger or just a developmentledger. All the communication to the ledger goes through the agencies. Also, allthe Aries agent-to-agent communication goes from agency to agency, as you cansee in the following drawing.

The application logic is inside the agent controllers. The next imageillustrates when a mobile controller communicates findy-agent, it calls theagency's CA API and receives notifications.

Likewise, when a SA communicates with an agency, it calls the agency's CA APIand receives notifications and questions from the agency.The image below shows how CAs communicate with Aries.

Findy agency offers an extensive set of commands by itself, and other commandset exists infindy-agent-cli. In addition to that, many other tasks have tobe taken care of before a full agency setup can work. The following use casediagram shows most of the tasks and uses system boundaries to illustrate whichof them are directly operable by findy-agent or findy-agent.

As the diagram shows the prerequisites to start the agency are:

• A steward wallet is available, or you have seed to create steward wallet byyour self.
• You have to set up a server environment, like volumes for wallets, anddatabases.

During the agency run, you can monitor its logs. Between the starts, you canreset the all cloud agent allocations, or you can edit the register JSON. Note,that you cannot add new allocations only by editing the register JSON. The wholehandshake procedure must be performed.

When an agency is running, you can operate with it findy-agent executable whenyou use it as a client mode. The following use case diagram shows the essentialcommands after the agency started.

The use case diagram is a summary of the creation commands available. With thesecommands, you can create all that is needed in the identity network from thecommand line.

Findy agency is a service that implements an Aries compatible identity agents.What makes it an agency is that it's multi-tenant. It can easily serve thousands of edgeagents with one installation and with modest hardware.

Each CA controller gets a corresponding cloud agent as its service. The followingdeployment diagram illustrates the main components of the typical system wherefindy-agent is installed on a single node, and a wallet application is runningas PWA in the browser. The picture includes an external agent that is running onanother node (grey).

As the diagram shows, the main wallet of each agent is on the server, our wecould say it is in the cloud. That simplifies things a lot. We can have cloudbackups, recovery, and most importantly, it makes it possible to 24/7 presencein the cloud for each agent.

The issuer server could run on the same node as the agency, but the most commoncase is where it runs on its own. Typical SA includes application logic, and theissuing credential is a small part. The API between SA and the agency is quitestraightforward. The API runs on DIDComm similarly to mobile agents.

The following sequence diagram shows an example of how two cloud agents sendmessages to each other and save them to Bolt DB (Go implementation of LMBD). Thediagram shows the "transactional" implementation of HTTP-based message transfer.Receiving the message is done by first saving the incoming message to thedatabase and after that returning OK. If the receiver cannot save the incomingmessage, it returns an error code.

The next UML diagram implements the connection protocol as a finite statemachine, which has two top-level states: Waiting Start Cmd/Msg, andConnectionProtocolRunning. The protocol waits for either a command or a message.The command can be an InvitationCmd, which means that we have received aninvitation. In the current system, invitations are coming from other channels,and they are not protocol-messages (out-bound). The invitation includesconnection information to an agent like an endpoint and its public key. Theagent who receives the InvitationCmd sends a connection request message(ConnReq) to the receiving agent and starts to wait for a connection responsemessage (ConnResp). As the state machine shows, the receiving agent sends theconnection response back and finalizes its state machine. The agent who startedthe connection protocol receives the connection response message and finalizesits state machine.

The previously seen ConnectionProtocolRunning state divides two separate statemachines. The left sub-state machine is on when the agent is an inviter, and theright-sided is on when the agent is an invitee. This same basic structure is inall of the Aries protocol state machines. One of the agents initiates theprotocol, which gives the roles for them: inviter/invitee, issuer/holder,prover/verifier. However, most of the Aries protocols are more complicatedbecause both of the roles can initiate the protocol, and depending on themessage it sends, the role it gets for the protocol.

The issuing protocol state machine is waiting for a command to initiate theprotocol or incoming message to connect already started protocol (Waiting StartCmd/Msg -state). If an agent is in an issuer's role, it can start the protocolby sending a credential offer message (CredOffer). It can do that by sendingCredOfferCmd to the protocol processor, as we can see in the state machinediagram. Similarly, when an agent is in a holder's role, it can start theprotocol by sending a credential-propose message (CredProp), and it can do thatby sending CredProposeCmd to the protocol processor. Naturally, when an agentreceives either an offer or a propose, it responses accordingly. Receiving acredential offer puts an agent to a holder's role, and receiving a credentialpropose puts an agent to an issuer's role. Now we should understand how we havefour related ways to initiate the protocol state machine for an issuing protocol(state transition from Waiting Start Cmd/Msg -state toIssuingProtocolRunning-state). The rest of the protocol is quite clear and easyto understand from the state machine diagram.

• Tests for fail cases. WIP
• Interoperability testing with Aries testing harness.
• Indy wallet implementation with storage plug-in like PostgreSQL. Done: wehave wallet pool.
• Crypto implementations for different server types, AWS Nitro, ...
• Backup system for current docker volumes.
• The PSM runner for restarts and non-delivery messages and cleanup oldones.Partially done, we have data pump and archiving now.
• Haven't been able to test with stable ledger.
• Check if we have received the message already.
• Check incoming order of the messages, same as declared in the PSM.
• libindy under pressure, wallet handles, etc. Done: wallet pool, more testsneeded
• API for browsing connections, credentials etc. Done: we havevault
• PSM archive logic, dedicated storage for persistent client data (see thePSM runner).
• Credential revocation, if wanted to use (check upcoming anoncreds 2.0)
• Skipping DID-writes to ledger for individuals: moving to fullpeer did.
• Realpeer did implementation. (Staticdid:peer)
• Agent permissions. Separation of individuals and services in on-boarding-> e.g. no credential issuing for individuals (maybe Agency types).