findy-common-ts

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. Follow the blog for updates.

Getting Started

Findy Agency is a collection of services (Core, Auth, Vault and Web Wallet) that provide full SSI agency along with a web wallet for individuals. To start experimenting with Findy Agency we recommend you to start with the documentation and set up the agency to your localhost environment.

• Documentation
• Instructions for starting agency in Docker containers

Project

Module that provides common findy-agent usage functionality.

Description

This library provides utilities for connecting to Findy Agency from a Node.js-application. It provides

• means to authenticate to agency using findy auth services
• helpers for opening and making the gRPC API calls
• TS code generated from gRPC API proto file

The focus is to provide utilities especially long-running webapps that intend to issue and verify credentials.

Usage

1. Run

   npm install @findy-network/findy-common-ts

2. Either use cloud agency installation or setup agency to your local environment. You need following settings for a successful connection (defaults for local):

   • Authentication service URL (http://localhost:8088)
   • Core agency server address (localhost)
   • Core agency server port (50052)
   • Path to core agency TLS cert files (/path/to/this/repo/tools/config/cert) -- unless the certificate is issued by a trusted issuer

3. Check example how to authenticate to agency and connect to other agents using the library. More advanced examples can be found in sample webapp implementation.

Example

This example shows how to onboard an agent to Findy agency, create invitation and send a basic message to the new connection once the connection is established.

For more examples, check e2e tests or sample webapp implementation: issuer-tool.

import {
  createAcator,
  openGRPCConnection,
  agencyv1
} from '@findy-network/findy-common-ts';

const start = async (): Promise<void> => {
  const authUrl = 'http://localhost:8088';
  const userName = `my-chat-bot`;
  // Authenticator key - should be kept secret
  const key =
    '15308490f1e4026284594dd08d31291bc8ef2aeac730d0daf6ff87bb92d4336c';
  const serverAddress = 'localhost';
  const serverPort = 50052;
  const certPath = './tools/config/cert';

  // Create authenticator.
  // Authenticator onboards the agent automatically if this is the first time
  // we are connecting to auth service.
  const acatorProps = {
    authUrl,
    userName,
    key
  };
  const authenticator = createAcator(acatorProps);

  // Open gRPC connection to core agency
  const grpcProps = {
    serverAddress,
    serverPort,
    certPath
  };

  const connection = await openGRPCConnection(grpcProps, authenticator);
  const { createAgentClient, createProtocolClient } = connection;
  const agentClient = await createAgentClient();
  const protocolClient = await createProtocolClient();

  // Start listening to agent notifications
  const options = {
    protocolClient: protocolClient
  };
  await agentClient.startListeningWithHandler({
    DIDExchangeDone: (info, data) => {
      // connection established, send message to new connection
      const connectionId = info.connectionId;
      const basicMsg = new agencyv1.Protocol.BasicMessageMsg();
      basicMsg.setContent('Hello world');

      protocolClient.sendBasicMessage(connectionId, basicMsg);
    }
  }, options);

  // Create invitation. Copy the invitation from the console and use it to connect e.g.
  // with web wallet user.
  const invMsg = new agencyv1.InvitationBase();
  invMsg.setLabel(userName);
  const invResult = await agentClient.createInvitation(invMsg);
  console.log(
    'Connect using this invitation and I will greet you!',
    invResult.getJson()
  );
};

Development

1. Install typescript

   npm install -g typescript

2. Install deps

   npm install

3. Run unit test

   npm test

4. Run e2e test

   npm run e2e