openpubkey-js

TypeScript implementation of the OpenPubKey protocol.

This library is a complete rewrite of the official Go implementation, providing the same functionality for JavaScript/TypeScript environments. It works in both Node.js and browsers.

Installation

npm install @sourcenetwork/openpubkey-js

What is OpenPubKey?

OpenPubKey binds cryptographic keys to OpenID Connect identities without requiring modifications to identity providers.

Usage

Node.js

import { OpkClient, GoogleOp, Verifier } from '@sourcenetwork/openpubkey-js';

// Create a client with Google as the identity provider
const op = new GoogleOp();
const client = await OpkClient.newClient(op);

// Authenticate and get a PK Token
const pkToken = await client.auth();

// Sign a message
const signedMessage = await pkToken.newSignedMessage(
  new TextEncoder().encode('Hello, World!'),
  client.getSigner()
);

// Verify the PK Token (throws on failure)
const verifier = await Verifier.newVerifier(op);
await verifier.verifyPKToken(pkToken);

Browser

import {
  OpkClientBrowser,
  GoogleBrowserOp,
} from '@sourcenetwork/openpubkey-js';

// Create browser-compatible client
const op = new GoogleBrowserOp({
  clientID: 'your-google-client-id',
  redirectURI: 'https://yourapp.com/callback',
});

const client = await OpkClientBrowser.newClient(op);

// This will redirect to Google for authentication
await client.auth();

Supported Identity Providers

• Google (Node.js and Browser)
• GitHub Actions
• GitLab CI
• Azure
• Generic OIDC providers

Features

• PK Tokens: Create and verify OpenPubKey tokens
• GQ Signatures: Privacy-preserving signatures using the GQ scheme
• Cosigners: Multi-factor authentication support
• Compact Format: Efficient token serialization

API Reference

Core Classes

• OpkClient / OpkClientBrowser - Main client for authentication
• PKToken - OpenPubKey token containing identity and key binding
• Verifier - Verify PK Tokens and signatures
• Claims - Client Instance Claims for key binding

Providers

• GoogleOp / GoogleBrowserOp - Google OpenID Connect
• GitHubOp - GitHub Actions OIDC
• GitLabOp / GitLabCIOp - GitLab OIDC
• AzureOp - Azure AD

Utils

• gq256SignJWT / gq256VerifyJWT - GQ signature operations
• compactPKToken / splitCompactPKToken - Token serialization

Requirements

• Node.js >= 18.0.0
• For browsers: modern browsers with Web Crypto API support

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

Attribution

This library is a TypeScript port of the OpenPubKey Go library that follows the same specification and maintains API compatibility.

License

Apache-2.0