@welshare/react

Disclaimer, notes on maturity

This library is in Alpha / demo state at this moment. We're using it to review the security aspects while data is in transfer and in rest. There's absolutely no guarantee or warrant that at this point any data is safe, even though we're using resources that prioritize decentralization and resilience. Welshare Health wallets are controlled by cryptographic material which can be stored in non custodial / MPC environments (Privy). While that's considered very safe, we can't guarantee at this point that we've already got each aspect of inter application communication or key derivation features right, so don't connect wallets that store significant value with the welshare wallet yet.

Purpose

This is a React library that helps integrating with Welshare's sovereign data sharing platform. This package provides React hooks and components to connect applications with Welshare's wallet for secure data submission.

Installation

npm install @welshare/react
# or
yarn add @welshare/react
# or
pnpm add @welshare/react

Peer Dependencies

This package requires React 19+ as a peer dependency.

Prerequisites

You need to register an app identifier using the Welshare Wallet frontend first: https://wallet.welshare.app/application. We're referring to this as your-application-id from here on.

If you want to submit questionnaire data, your application must first register a new questionnaire definition. You can also reuse an existing questionnaire id to let users contribute responses to another app's questionaire, but that's not highly encouraged at this point.

Data Submissions

At the moment there are only two supported submission types: Fhir compatible QuestionnaireResponses and our custom "Reflex" app submissions. Both types are identified by schema uids that are accessible on the Schemas export.

export const Schemas = {
  QuestionnaireResponse: "b14b538f-7de3-4767-ad77-464d755d78bd",
  BinaryFile: "9d696baf-483f-4cc0-b748-23a22c1705f5",
};

To submit questionnaires using custom frontends, you'll use the useWelshare hook to open a wallet dialog that lets your application talk to the user's connected wallets (using derived storage keys). All communication with the Welshare infrastructure happens inside that browser window.

Code Sample

import { ConnectWelshareButton, Schemas, useWelshare } from "@welshare/react";

export function QuestionnaireForm() {
  const { isConnected, openWallet, submitData } = useWelshare({
    applicationId: <your-application-id>,
    environment: "development", //optional, at the moment the environment is always development
    callbacks: {
      onUploaded: (payload) => console.log('Data uploaded:', payload),
      onError: (error) => console.error('Error:', error),
      onSessionReady: (storageKey) => console.log('Session ready:', storageKey),
    }
  });

  const handleSubmit = () => {
    //response is a QuestionnaireResponse compatible object
    submitData(Schemas.QuestionnaireResponse, response);
  };

  // using the `ConnectWelshareButton` is not mandatory. Use your own buttons if you feel like it.
  return (
    <div>
      {!isConnected ? (
        <ConnectWelshareButton openWallet={openWallet}>
          Connect to Welshare
        </ConnectWelshareButton>
      ) : (
        <form>
          {/* ... some form that collects your response data ... */}
          <button onClick={() => handleSubmit(response)} disabled={isSubmitting}>
            {isSubmitting ? 'Submitting...' : 'Submit Data'}
          </button>
        </form>
      )}
    </div>
  );
}

Binary file uploads (e.g. images)

Before data hits any server, the SDK encrypts all files with a new random symmetric AES (GCM / 256 bits) key. Users request a presigned upload url and post the encrypted file to an S3 compatible API that's currently operated by Welshare. Ultimately, they encrypt the encryption key for a Nillion owned BinaryData collection and store it across Nillion nodes (no single node can recover the key). At the time of insertion, they currently also grant ACL read rights for the application (Technically, this is the welshare builder keypair at the moment).

Upload via Wallet Dialog

const { isConnected, openWallet, uploadFile, submitData } = useWelshare({
  applicationId: process.env.NEXT_PUBLIC_WELSHARE_APP_ID || "",
});

// Upload file (wallet dialog handles auth)
const { url: uploadedFileUrl, binaryFileUid } = await uploadFile(
  userFile,
  `questionnaire/${questionnaireId}/${linkId}`
);

// Use in QuestionnaireResponse
const responseItem = {
  answer: [
    {
      valueAttachment: {
        id: binaryFileUid,
        contentType: userFile.type,
        size: userFile.size,
        title: userFile.name,
        url: uploadedFileUrl,
      },
    },
  ],
};

Binary files are addressed as valueAttachment items in FHIR. See https://www.hl7.org/fhir/questionnaireresponse.html

For applications that manage storage keypairs directly and need more control over the upload process, see the Binary File Uploads section in the SDK documentation.

API

supported callbacks

those are configured in the useWelshare options parameter and called back during interactions with the wallet dialog

  callbacks: {
    onUploaded?: (payload: SubmissionPayload<unknown>) => void;
    onError?: (error: string) => void;
    onSessionReady?: (sessionPubKey: string) => void;
    onDialogClosing?: () => void;
    onDialogReady?: () => void;
    onFileUploaded?: (insertedUid: string, url: string) => void
  }

Security Notes

No part of this application interacts with a "blockchain" (Nillion nodes are validated by a custom chain but that's relevant for end users' security or privacy).

The EVM addresses that control a user profile are never disclosed to third parties, hence they cannot correlate the wallet control keys with the keys that control the actual data.

The key derivation mechanism is used for creating self signed cryptographic authentication tokens, but the mechanism that keys are derived will very likely change in the future. Existing keys might render obsolete at that point which will require users to manually migrate their data. We don't guarantee that the current key derivation mechanism will be part of this SDK's exposed feature set forever. However, users will always be able to derive keys on their own, as long as they know the rules and don't lose the required secret inputs (e.g. signing keys or salts).

Data is stored on nilDB (by Nillion), a protocol that enforces access control lists, encrypts data at rest and stores records redundantly. Plain data documents are not generally encrypted at this point in time, however. Binary uploads are end to end encrypted in the way that's described above.

All data that's sent to nilDB via user client is exclusively controlled by the user's own key material. Welshare only delegates NUCs (access rights) to the users. Be aware that right now the welshare builder key can read any data users upload. This will structurally improve once Nillion supports delegated reads for non builder grantees. Welshare's goal is to make user originated information available exclusively for code that runs in execution environments trusted by the users.

License

MIT. See the LICENSE file for details.

Contact

Get in touch on Telegram. Check https://welshare.health