npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@pcd/passport-interface

v0.15.0

Published

Install the `@pcd/passport-interface` package with npm:

Downloads

2,274

Readme

| This package contains code that defines the API of the passport server and client, and enables developers (both us, and third party developers) to communicate with those two applications. For example, this package contains code that enables you to construct a URL that requests a particular PCD from the passport webapp. | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

🛠 Install

Install the @pcd/passport-interface package with npm:

npm i @pcd/passport-interface

or yarn:

yarn add @pcd/passport-interface

📜 Usage

The communication between users and passport webapp is mostly via a popup, which redirects to the webapp according to the URL and its search parameters in the same popup. Once the webapp generates the requested content, the popup automatically closes, and the resulting content can be accessed through a React hook.

sequenceDiagram
    User app->>User app: constructURL(PCD)
    User app->>Popup route: openPopupRoute(URL)
    Popup route->>Passport popup: redirectToPassportWebapp(URL)
    Passport popup->>Passport popup: getPCD(PCD)
    Passport popup->>Popup route: redirectToPopupRoute(PCD)
    Popup route-->>User app: return <<PCD>>

Below, it will be shown how the functions of this package can be used in such a flow.

For more detailed information about the package's functions and types, please refer to the documentation site.

Using the passport popup

You can use the usePassportPopupSetup React hook to set up necessary passport popup logic on a specific route (e.g. /popup) and communicate with the passport webapp. Basically, it redirects the user to the webapp passport or initial page based on the search parameters of the URL, leveraging cross-origin communication between windows.

import { usePassportPopupSetup } from "@pcd/passport-interface"

export default function Popup() {
    const error = usePassportPopupSetup()

    return <div>{error}</div>
}

Then the usePassportPopupMessages React hook can be used to process the results of the requests. It listens for incoming messages from the other browsing context (i.e. the popup) and store them in a state variable.

import { usePassportPopupMessages } from "@pcd/passport-interface";

export default function App() {
  const [passportPCDString] = usePassportPopupMessages();

  useEffect(() => {
    console.log(passportPCDString);
  }, [passportPCDString]);
}

Adding a PCD to with the passport popup

You can generate a PCD and add it to the passport with constructPassportPcdProveAndAddRequestUrl.

import { EdDSAPCDPackage } from "@pcd/eddsa-pcd"
import { constructPassportPcdProveAndAddRequestUrl, openPassportPopup } from "@pcd/passport-interface"
import { ArgumentTypeName } from "@pcd/pcd-types"

const url = constructPassportPcdProveAndAddRequestUrl<typeof EdDSAPCDPackage>(
    "https://zupass.org",
    window.location.origin + "/popup",
    EdDSAPCDPackage.name,
    {
        id: {
            argumentType: ArgumentTypeName.String
    },
        message: {
            argumentType: ArgumentTypeName.StringArray,,
            value: ["0x32"]
        },
        privateKey: {
            argumentType: ArgumentTypeName.String,
            userProvided: true
        }
    },
    { title: "EdDSA Signature Proof" }
)

openPassportPopup("/popup", url)

Or add a previously generated serialized PCD with constructPassportPcdAddRequestUrl.

import { constructPassportPcdAddRequestUrl, openPassportPopup } from "@pcd/passport-interface"

// This code could be on your server.
const pcd = await prove({
    id: {
        argumentType: ArgumentTypeName.String
    },
    message: {
        argumentType: ArgumentTypeName.StringArray,,
        value: ["0x32"]
    },
    privateKey: {
        argumentType: ArgumentTypeName.String,
        value: "0x42"
    }
})

const serializedPCD = await serialize(pcd)

const url = constructPassportPcdAddRequestUrl(
    "https://zupass.org",
    window.location.origin + "/popup",
    serializedPCD
)

openPassportPopup("/popup", url)

Getting a PCD with the passport popup

You can get a PCD from the passport that already exists in the user's local storage with getWithoutProvingUrl.

import { EdDSAPCDPackage } from "@pcd/eddsa-pcd";
import {
  getWithoutProvingUrl,
  openPassportPopup
} from "@pcd/passport-interface";

const url = getWithoutProvingUrl(
  "https://zupass.org",
  window.location.origin + "/popup",
  EdDSAPCDPackage.name
);

openPassportPopup("/popup", url);

Or you can prove a claim and get its PCD with constructPassportPcdGetRequestUrl.

import { EdDSAPCDPackage } from "@pcd/eddsa-pcd";
import {
  constructPassportPcdGetRequestUrl,
  openPassportPopup
} from "@pcd/passport-interface";
import { ArgumentTypeName } from "@pcd/pcd-types";

const url = constructPassportPcdGetRequestUrl<typeof EdDSAPCDPackage>(
  "https://zupass.org",
  window.location.origin + "/popup",
  EdDSAPCDPackage.name,
  {
    id: {
      argumentType: ArgumentTypeName.String
    },
    message: {
      argumentType: ArgumentTypeName.StringArray,
      value: ["0x32"]
    },
    privateKey: {
      argumentType: ArgumentTypeName.String,
      userProvided: true
    }
  }
);

openPassportPopup("/popup", url);

Interacting with the passport webapp directly without popup

If you wish to add or get a PCD from the passport webapp without relying on a popup interface but instead managing the outcome of the request on your server, you can achieve this by specifying an alternative return URL. This return URL could be a designated endpoint on your server, responsible for processing the request and its subsequent actions.

import { EdDSAPCDPackage } from "@pcd/eddsa-pcd";
import { constructPassportPcdGetRequestUrl } from "@pcd/passport-interface";
import { ArgumentTypeName } from "@pcd/pcd-types";

const url = constructPassportPcdGetRequestUrl<typeof EdDSAPCDPackage>(
  "https://zupass.org",
  "https://your-server.org/verify", // This endpoint will handle the request's results.
  EdDSAPCDPackage.name,
  {
    id: {
      argumentType: ArgumentTypeName.String
    },
    message: {
      argumentType: ArgumentTypeName.StringArray,
      value: ["0x32"]
    },
    privateKey: {
      argumentType: ArgumentTypeName.String,
      userProvided: true
    }
  },
  {
    genericProveScreen: true
  }
);

A real use case could be a Telegram bot that redirects users to the passport webapp to allow them to enter their private key to sign a message and create a EdDSA PCD. The return URL in this case will be an endpoint in the bot's server that adds the user to a Telegram group after verifying the PCD.