@indiciopbc/proven-id-js

v0.1.3

Published

12 days ago

Proven ID JavaScript — self-contained, embeddable browser bundle for the verification UI.

0High
0Medium
0Low

lynnbendixsen

reflectivedevelopment

dbluhm

mikekebert

@indiciopbc/proven-id-js

Self-contained, framework-free browser bundle for the Proven ID verification UI. It injects a block-level element that renders instructions, a QR code / deep link, and status updates, all driven entirely by WebSocket messages from @indiciopbc/proven-id-lib on your backend.

For the conceptual walkthrough — what the user sees at each step and why — see SPEC.md §4. This README covers installing and configuring the actual bundle.

Install / include

As an npm package, bundled into your own frontend:

yarn add @indiciopbc/proven-id-js

import ProvenIdJS from "@indiciopbc/proven-id-js";

Or as a plain <script> tag, which exposes window.ProvenIdJS without any bundler:

<script src="/proven-id.js"></script>

The built artifact is dist/proven-id.js (a single IIFE, qrcode bundled in — no other runtime dependency). If you don't want it as an npm dependency of your frontend build, you can serve the file straight from node_modules/@indiciopbc/proven-id-js/dist/proven-id.js as a static asset. This repo's demo does exactly that in dev without any bundler integration — see ui/vite.config.ts's serve-proven-id-js plugin, which streams the built file at /proven-id.js, and ui/index.html's <script src="/proven-id.js"></script>.

Quick start

window.ProvenIdJS.init({
  wsUrl: "wss://your-backend.example.com/ws",
  containerId: "proven-id-container",
});

<div id="proven-id-container"></div>

wsUrl must point at the path your backend mounted with provenLib.attachWebSocketServer() (see @indiciopbc/proven-id-lib README). Real example, from this repo's ui/src/UI/Verify.tsx:

useEffect(() => {
  const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
  window.ProvenIdJS.init({
    wsUrl: `${protocol}//${window.location.host}/ws`,
    containerId: "proven-id-container",
  });
}, []);

init() renders the instructions state immediately into containerId (creating the element and appending it to <body> if it doesn't already exist) — no WebSocket connection is opened until the user clicks "Get Started".

`ProvenIdJsConfig`

| Field | Required | Description | |---|---|---| | wsUrl | Yes | WebSocket URL of your backend (ws:// or wss://). | | containerId | Yes | Id of an existing element to render into, or the id to assign to a container the client creates and appends to <body>. | | title | No | Heading shown on the instructions state. Default: "Verify your identity". | | instructions | No | Instructional copy on the instructions state. Default: a generic Holdr+ install prompt. | | appDownload | No | { ios?, android? } app-store links shown on the instructions state. Defaults point at the public Holdr+ app-store/Play-store listings. |

UI states

The client is a state machine driven entirely by inbound WebSocket messages (types are specified in SPEC.md §5):

| State | Trigger | UI shown | |---|---|---| | instructions | Initial load | App download links and "Get Started" button | | connecting | "Get Started" clicked, WebSocket opened, awaiting invitation | Spinner | | qr_ready | invitation message received | QR code + tappable deep link | | processing | processing message received | "Verifying…" spinner | | success | result with status: "success" | Success message, or redirect (see below) | | failed | result with status: "failed" | Failure message per code/message | | error | result with status: "error" | Error message per code/message | | expired | session_expired message | "Start Again" button |

Redirects. On a success result, if redirect_url is present the client navigates there immediately (location.assign) instead of rendering a message — redirect always wins over message/code display.

Restart. From the expired state, "Start Again" reuses the existing WebSocket connection if it's still open (sending { type: "restart" }, which @indiciopbc/proven-id-lib's WebSocket server handles by re-requesting a fresh invitation) and transparently reconnects otherwise.

Styling & customization

The client injects its own scoped styles (injectStyles) and owns the full contents of the container element — there are currently no theming hooks, slot overrides, or CSS custom properties exposed beyond title/instructions/appDownload. If you need different visuals, the options today are forking the bundle or driving your own UI off the same WebSocket protocol described in SPEC.md §5 instead of using this package.

Manual/local testing

demo/index.html in this package is a standalone harness with a mock WebSocket — useful for exercising every UI state without a live backend.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@indiciopbc/proven-id-js

Install / include

Quick start

ProvenIdJsConfig

UI states

Styling & customization

Manual/local testing

See also

`ProvenIdJsConfig`