{"id":16714,"library":"better-auth-corepass-passkey","title":"Better Auth CorePass Passkey Plugin","description":"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.","status":"active","version":"0.1.18","language":"javascript","source_language":"en","source_url":"https://github.com/CorePass/better-auth-corepass-passkey","tags":["javascript","typescript"],"install":[{"cmd":"npm install better-auth-corepass-passkey","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-corepass-passkey","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-corepass-passkey","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core authentication framework that this package plugs into.","package":"better-auth","optional":false},{"reason":"Provides the base passkey registration and verification functionality that this plugin extends.","package":"@better-auth/passkey","optional":false}],"imports":[{"note":"This package ships as an ES Module. `createCorePassPasskeyPlugin` is the primary factory function used to integrate CorePass enrichment into `better-auth`.","wrong":"const createCorePassPasskeyPlugin = require('better-auth-corepass-passkey').default;","symbol":"createCorePassPasskeyPlugin","correct":"import { createCorePassPasskeyPlugin } from 'better-auth-corepass-passkey'"},{"note":"Import this type using `import type` for type-checking purposes in TypeScript environments to configure the plugin.","wrong":"import { CorePassPasskeyPluginOptions } from 'better-auth-corepass-passkey';","symbol":"CorePassPasskeyPluginOptions","correct":"import type { CorePassPasskeyPluginOptions } from 'better-auth-corepass-passkey'"},{"note":"The `CorePassProfile` type defines the structure of the enriched CorePass user profile data available on the `better-auth` session object.","wrong":"import { CorePassProfile } from 'better-auth-corepass-passkey';","symbol":"CorePassProfile","correct":"import type { CorePassProfile } from 'better-auth-corepass-passkey'"}],"quickstart":{"code":"import { AuthService } from 'better-auth';\nimport { createPasskeyPlugin } from '@better-auth/passkey';\nimport { createCorePassPasskeyPlugin } from 'better-auth-corepass-passkey';\nimport express from 'express';\n\n// In a production environment, these should be loaded from secure environment variables.\nconst COREPASS_PUBLIC_KEY = process.env.COREPASS_PUBLIC_KEY ?? 'YOUR_COREPASS_PUBLIC_KEY_HERE';\nconst WEB_AUTHN_RP_ID = process.env.WEB_AUTHN_RP_ID ?? 'localhost'; // Your application's domain\nconst WEB_AUTHN_RP_NAME = process.env.WEB_AUTHN_RP_NAME ?? 'My Secure App'; // Your application's name\n\nasync function setupAuthService() {\n  const authService = new AuthService({\n    // ... other AuthService configuration options\n    plugins: [\n      createPasskeyPlugin({\n        rpId: WEB_AUTHN_RP_ID,\n        rpName: WEB_AUTHN_RP_NAME,\n        // other passkey plugin options, e.g., challenge timeout\n      }),\n      createCorePassPasskeyPlugin({\n        corePassPublicKey: COREPASS_PUBLIC_KEY,\n        // requireO18y: true, // Example: Require user to be over 18\n        // requireKyc: true,  // Example: Require KYC verification\n        // allowNetwork: ['mainnet', 'testnet'], // Example: Allowed CorePass networks\n      })\n    ],\n    // ... additional AuthService options, e.g., session management\n  });\n\n  const app = express();\n  app.use(express.json()); // Middleware to parse JSON request bodies\n  app.use('/auth', authService.router); // Mount Better Auth routes at /auth\n\n  // Example protected route, accessible only after successful passkey registration\n  // and CorePass enrichment, if configured to be required.\n  app.get('/api/profile', (req, res) => {\n    const session = authService.getSession(req); // Assuming a session is established\n    if (session && session.user && session.user.profile && 'coreId' in session.user.profile) {\n      return res.json({ message: `Welcome, CorePass user!`, profile: session.user.profile });\n    }\n    res.status(401).send('Unauthorized: CorePass profile not found or expired.');\n  });\n\n  const PORT = process.env.PORT || 3000;\n  app.listen(PORT, () => {\n    console.log(`Better Auth service running on http://localhost:${PORT}/auth`);\n    console.log(`Example protected endpoint: http://localhost:${PORT}/api/profile`);\n  });\n}\n\nsetupAuthService().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"fix":"Update all client-side code and API calls to send CorePass enrichment data to the new `/webauthn/data` endpoint, ensuring your `better-auth` base path is prefixed correctly (e.g., `/auth/webauthn/data`).","message":"The enrichment endpoint for CorePass data was renamed from `/passkey/data` to `/webauthn/data`. Any existing client-side integrations sending data to the old path will fail.","severity":"breaking","affected_versions":">=0.1.9 <0.1.13"},{"fix":"For anonymous bootstrap flows that require access to specific routes before passkey registration, configure the `allowRoutesBeforePasskey` option in the `createCorePassPasskeyPlugin` settings to permit access to those paths.","message":"The plugin enforces 'strict passkey-only access' by default, meaning users without at least one registered passkey are blocked from most authentication endpoints. This can unexpectedly restrict anonymous bootstrap flows.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"If immediate user access is desired after passkey registration, you must explicitly set `finalize: 'immediate'` within the `createPasskeyPlugin` options (or the appropriate setting if overridden by this plugin).","message":"By default, `finalize: 'after'` is enabled, which holds users on an 'on hold' status until CorePass enrichment data is successfully received. This means users are not immediately active post-passkey registration.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your application handles cases where `user.profile.coreId` or other `corepass_profile` fields might be missing due to expiry. Implement a mechanism to prompt users for re-enrichment via the CorePass app if their profile data has expired.","message":"If `userData.dataExp` (data expiry in minutes) is configured, the `corepass_profile` data will be automatically omitted from the session's `user.profile` object once it expires, requiring re-enrichment.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify that the Core ID being sent from the CorePass application is valid. Additionally, ensure the `allowNetwork` array in your `createCorePassPasskeyPlugin` options includes the specific CorePass blockchain network(s) from which you expect to receive data.","cause":"The Core ID provided during the CorePass enrichment process is either syntactically invalid or its blockchain network is not included in the `allowNetwork` option within the plugin configuration.","error":"Invalid Core ID or network not allowed."},{"fix":"Confirm that your client-side code sends enrichment data to the correct `/webauthn/data` path relative to your `better-auth` base path (e.g., `/auth/webauthn/data` if your `AuthService` router is mounted at `/auth`). Also, ensure the `createCorePassPasskeyPlugin` is correctly included in the `plugins` array of your `AuthService` instance.","cause":"The client-side application is attempting to send CorePass enrichment data to an incorrect or unmounted endpoint, or the `better-auth` service is not configured to handle the `/webauthn/data` route.","error":"POST /auth/webauthn/data 404 Not Found"},{"fix":"Adjust your client-side flow to ensure an email address is provided either in the request body of the initial anonymous sign-in or is guaranteed to be delivered via CorePass enrichment, satisfying the configured plugin requirements.","cause":"One of the email requirement options (`requireRegistrationEmail`, `requireEmail`, or `requireAtLeastOneEmail`) is set to `true` in the plugin configuration, but no email address was provided during the initial passkey registration or through CorePass enrichment.","error":"Error: Account creation failed: Email required."},{"fix":"Review the plugin's configuration for any uniqueness requirements (e.g., unique email, unique Core ID). Investigate the user flow to ensure that duplicate registrations are handled gracefully, perhaps by prompting for a different credential or linking to an existing account.","cause":"An operation (e.g., updating user data during enrichment) resulted in a conflict, likely due to a uniqueness constraint violation (e.g., attempting to register an email or Core ID that already exists for another user).","error":"Error: Cannot update user: conflict."}],"ecosystem":"npm"}