Canonical Cubid starter v3

Full-stack identity, verification, comms, and recovery in one Next.js app.

This starter demonstrates the modern `@cubid/*` package family from `Cubid-Me/cubid-sdk`. Server calls use dapp credentials only on API routes. Browser flows use OIDC PKCE, hosted verification, notification preferences, and recoverable-wallet launchers without exposing server secrets.

Identity aggregation

Resolve app users, read disclosed stamps, and treat humanity score as an app-scoped signal.

Proof of personhood

Launch Cubid-hosted verification flows without moving private provider logic into your app.

Passkey recovery

Model Cubid as a recovery provider for host-created wallets, not as a wallet generator.

Unified comms

Let signed-in users manage notification channels and category preferences through the Cubid platform.

Starter contract

Cubid is identity first.

Sign-in-with-Cubid is a passkey-enabled add-on. ClearPass Verify, stamps, score, and OIDC claims are identity signals for your app.

Dapp API keys stay server-side in `src/app/api/*`.

Wallet examples are recovery-only: no Cubid wallet creation, no normal transaction signing.

v1 and v2 starters are deprecated archive references, not implementation sources.

Server API demo

These actions run through a Next.js API route using `@cubid/core`. Missing server credentials return a safe setup response instead of leaking secrets into the browser.

Register or resolve a user

Send an email to ensureUserByEmail and capture the returned app-scoped Cubid id.

Use the Cubid id for follow-up calls

The returned id is app-scoped. Use it for identity, stamps, score, and recovery metadata calls.

OperationCubid app-scoped user id

Request

The browser posts this sanitized payload to the local Next.js API route. That route creates the @cubid/core client with server-only env vars, calls Cubid, and returns a redacted starter response.

Local route

POST /api/cubid/server-demo

Server package

@cubid/core

Credentials

Reads CUBID_API_BASE_URL, CUBID_API_KEY, and optional CUBID_DAPP_ID only inside the API route.

Registration request

{
  "body": {
    "email": "demo@example.com",
    "operation": "ensure-user"
  },
  "headers": {
    "content-type": "application/json"
  },
  "method": "POST",
  "route": "/api/cubid/server-demo"
}

Follow-up request

{
  "body": {
    "operation": "identity",
    "providerKey": "",
    "recoveryBundleId": "",
    "userId": ""
  },
  "headers": {
    "content-type": "application/json"
  },
  "method": "POST",
  "route": "/api/cubid/server-demo"
}

Registration response

Register a user to get their Cubid id.

Follow-up response

Use the returned Cubid id to run a follow-up call.

Browser UX demo

Add the browser-safe `NEXT_PUBLIC_CUBID_*` values from `.env.example` to enable Login with Cubid, ClearPass Verify, notification preferences, and recovery launchers.

Missing browser-safe config: clearPassPageId, clientId, issuer, passportBaseUrl, redirectUri

SIWC / SSO protocol demo

This panel starts Cubid-hosted OIDC from starter-owned server routes. A passkey scoped to `cubid.me` does not sign into the starter by itself; an existing Cubid SSO session may simply skip the passkey ceremony.

{
  "authenticated": false,
  "status": "not_signed_in",
  "trace": []
}

Cubid env reference

These are the settings this starter needs for live Cubid identity, hosted verification, comms, and recovery flows. Keep server-only values out of `NEXT_PUBLIC_*`.

Open Cubid Admin

Required for Cubid to work

Variable	Scope	Used for	Where to get it
NEXT_PUBLIC_CUBID_ISSUER_URL	Browser-safe	Login with Cubid / OIDC PKCE discovery.	Cubid issuer URL, usually https://id.cubid.me.
NEXT_PUBLIC_CUBID_OIDC_CLIENT_ID	Browser-safe	Browser sign-in launch and callback handling.	Create or copy the OIDC client id in Cubid Admin.
NEXT_PUBLIC_CUBID_REDIRECT_URI	Browser-safe	OIDC callback validation.	Register the same local callback URL on the Cubid OIDC client.
NEXT_PUBLIC_CUBID_PASSPORT_BASE_URL	Browser-safe	Hosted Cubid browser flows.	Cubid hosted app/API origin, usually https://passport.cubid.me.
CUBID_SIWC_ISSUER_URL	Server-only	Server-mediated SIWC discovery and issuer validation.	Use https://id.cubid.me for production.
CUBID_SIWC_CLIENT_ID	Server-only	Server-mediated authorization and code exchange.	Copy the registered relying-party client id from Cubid Admin.
CUBID_SIWC_REDIRECT_URI	Server-only	The starter-owned SIWC callback route.	Register the exact local, preview, or production callback URL.
CUBID_API_BASE_URL	Server-only	Server API demo calls through @cubid/core.	Cubid API origin, usually https://passport.cubid.me.
CUBID_API_KEY	Server-only	Dapp API calls for users, identity, score, stamps, and recovery metadata.	Generate or copy your dapp API key in Cubid Admin.

Optional or flow-specific

CUBID_DAPP_ID

Server-only

Endpoints that require an explicit dapp id. Set it when your Cubid environment or API key is scoped by dapp id.

NEXT_PUBLIC_CUBID_CLEARPASS_PAGE_ID

Browser-safe

ClearPass Verify launcher. Required only for the ClearPass Verify demo.