Better Auth CorePass Passkey Plugin

0.1.18 · active · verified Wed Apr 22

This package is a plugin for the Better Auth ecosystem, extending the functionality of the `@better-auth/passkey` plugin with CorePass-specific identity enrichment. It facilitates user registration via passkeys while integrating signed identity and profile data, such as Core ID, email, and KYC (Know Your Customer) flags, directly from the CorePass application. The plugin performs robust Ed448 signature verification on incoming enrichment data, validates Core IDs using `blockchain-wallet-validator`, and enforces configurable requirements like age verification (`requireO18y`, `requireO21y`) and KYC. It also dynamically updates user profiles and session data, including a `corepass_profile` with configurable expiry. Currently at version 0.1.18, the library exhibits a rapid release cadence with frequent updates and bug fixes, indicating active development. A key differentiator is its strict 'passkey-only access' policy, which blocks users without a registered passkey from most authentication endpoints, making it ideal for anonymous bootstrap flows requiring eventual strong identity binding.

Common errors

Warnings

Install

Imports

Quickstart

This quickstart demonstrates how to initialize `better-auth` with both the `@better-auth/passkey` and `better-auth-corepass-passkey` plugins. It sets up an Express server to expose the authentication routes and an example protected endpoint that relies on the CorePass profile data being present in the user's session.

import { AuthService } from 'better-auth';
import { createPasskeyPlugin } from '@better-auth/passkey';
import { createCorePassPasskeyPlugin } from 'better-auth-corepass-passkey';
import express from 'express';

// In a production environment, these should be loaded from secure environment variables.
const COREPASS_PUBLIC_KEY = process.env.COREPASS_PUBLIC_KEY ?? 'YOUR_COREPASS_PUBLIC_KEY_HERE';
const WEB_AUTHN_RP_ID = process.env.WEB_AUTHN_RP_ID ?? 'localhost'; // Your application's domain
const WEB_AUTHN_RP_NAME = process.env.WEB_AUTHN_RP_NAME ?? 'My Secure App'; // Your application's name

async function setupAuthService() {
  const authService = new AuthService({
    // ... other AuthService configuration options
    plugins: [
      createPasskeyPlugin({
        rpId: WEB_AUTHN_RP_ID,
        rpName: WEB_AUTHN_RP_NAME,
        // other passkey plugin options, e.g., challenge timeout
      }),
      createCorePassPasskeyPlugin({
        corePassPublicKey: COREPASS_PUBLIC_KEY,
        // requireO18y: true, // Example: Require user to be over 18
        // requireKyc: true,  // Example: Require KYC verification
        // allowNetwork: ['mainnet', 'testnet'], // Example: Allowed CorePass networks
      })
    ],
    // ... additional AuthService options, e.g., session management
  });

  const app = express();
  app.use(express.json()); // Middleware to parse JSON request bodies
  app.use('/auth', authService.router); // Mount Better Auth routes at /auth

  // Example protected route, accessible only after successful passkey registration
  // and CorePass enrichment, if configured to be required.
  app.get('/api/profile', (req, res) => {
    const session = authService.getSession(req); // Assuming a session is established
    if (session && session.user && session.user.profile && 'coreId' in session.user.profile) {
      return res.json({ message: `Welcome, CorePass user!`, profile: session.user.profile });
    }
    res.status(401).send('Unauthorized: CorePass profile not found or expired.');
  });

  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => {
    console.log(`Better Auth service running on http://localhost:${PORT}/auth`);
    console.log(`Example protected endpoint: http://localhost:${PORT}/api/profile`);
  });
}

setupAuthService().catch(console.error);

view raw JSON →