Cubid SDK Monorepo

This repo is the canonical public SDK home for Cubid.

Private backend concerns stay in cubid-monorepo: the hosted Identity app at https://id.cubid.me, Passport UI, Admin, OIDC issuer runtime, signing keys, provider secrets, passkey verification, migrations, and service-role access.

Package Matrix

Package	Purpose	Registry availability
@cubid/core	Runtime-agnostic Cubid foundation client for servers, workers, Deno, and Supabase Edge Functions.	npm + JSR
@cubid/auth	Runtime-agnostic OIDC and PKCE helpers for browser-safe Sign in with Cubid.	npm-only
@cubid/auth-react	React provider, hooks, callback helpers, and session controls for Sign in with Cubid.	npm-only
@cubid/aptos	Aptos-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/browser	Headless browser helpers for hosted verification, OTP, Allow Page, and provider handoff flows.	npm-only
@cubid/bitcoin	Bitcoin-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/cardano	Cardano-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/comms	Signed-in messaging profile helpers for Passport notification channels and preferences.	npm-only
@cubid/cosmos	Cosmos-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/react	React components and hooks built on @cubid/browser.	npm-only
@cubid/evm	EVM-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/near	NEAR-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/polkadot	Polkadot-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/solana	Solana-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/starknet	Starknet-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/stellar	Stellar-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/sui	Sui-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/tezos	Tezos-specific public wallet metadata, provider-adapter, and verification helpers.	npm-only
@cubid/wagmi	wagmi-specific React integration helpers built on @cubid/evm.	npm-only
@cubid/wallet-recovery	Browser/client helpers for hosted wallet recovery, user-authorized release completion, and bundle visibility.	npm-only
@cubid/wallet-recovery-react	React launch and completion ergonomics for wallet recovery flows.	npm-only
@cubid/web3	Frozen legacy shared-wallet compatibility package for older installs.	npm-only, compatibility-only
@cubid/web2	Frozen compatibility wrapper around @cubid/browser.	npm-only, deprecated
@cubid/web2-react	Frozen compatibility wrapper around @cubid/react.	npm-only, deprecated
@cubid/acceptance	Private local consumer-style acceptance harness.	Private, never published

@cubid/core is the only JSR package today because it is the only package with an explicit runtime-agnostic Deno and Supabase Edge contract. The auth, auth-react, browser, React, chain, wallet-recovery, and interim compatibility packages remain npm-only by design.

@cubid/web2 and @cubid/web2-react remain installable for older imports, but they are compatibility names only. New integrations should use @cubid/browser and @cubid/react.

@cubid/web3 also remains installable, but it is now a frozen compatibility package. New wallet integrations should use the dedicated chain packages for provider-adapter metadata and @cubid/wallet-recovery or @cubid/wallet-recovery-react for Cubid recovery flows.

API Reference

Machine-readable package reference artifacts live in docs/reference/.

• Human index: docs/reference/README.md
• JSON manifest: docs/reference/api/manifest.json
• Package JSON references:
  • docs/reference/api/core.json
  • docs/reference/api/auth.json
  • docs/reference/api/auth-react.json
  • docs/reference/api/aptos.json
  • docs/reference/api/browser.json
  • docs/reference/api/bitcoin.json
  • docs/reference/api/cardano.json
  • docs/reference/api/comms.json
  • docs/reference/api/cosmos.json
  • docs/reference/api/react.json
  • docs/reference/api/evm.json
  • docs/reference/api/near.json
  • docs/reference/api/polkadot.json
  • docs/reference/api/solana.json
  • docs/reference/api/starknet.json
  • docs/reference/api/stellar.json
  • docs/reference/api/sui.json
  • docs/reference/api/tezos.json
  • docs/reference/api/wagmi.json
  • docs/reference/api/wallet-recovery.json
  • docs/reference/api/wallet-recovery-react.json
  • docs/reference/api/web3.json

Shared-wallet migrations now have a dedicated guide:

• docs/engineering/web3-migration-guide.md

Recoverable-wallet hosted validation has a dedicated smoke strategy:

• docs/engineering/recoverable-wallet-hosted-smoke.md

HTTP API Docs

The OpenAPI source of truth for public Cubid HTTP APIs lives at api/openapi.yaml. Interactive local docs are served with Scalar at /docs/, and the Postman collection at api/postman_collection.json is generated from the OpenAPI spec.

• API docs workflow: docs/api-readme.md
• OpenAPI spec: api/openapi.yaml
• Generated Postman collection: api/postman_collection.json

Use these commands when editing HTTP API docs:

pnpm api:validate
pnpm api:postman
pnpm dev

Do not manually edit api/postman_collection.json; regenerate it from api/openapi.yaml.

Examples

• Passkey-first SIWC integration guide: docs/examples/passkey-first-siwc.md
• ClearPass Dashboard Vite auth example: docs/examples/clearpass-dashboard-auth-vite.md

For Sign in with Cubid, https://id.cubid.me is the stable public OIDC/SIWC issuer and protocol boundary. SDKs should use OIDC discovery from that issuer instead of calling Passport, Verify, Admin, or internal OIDC interaction routes directly. https://login.cubid.me may remain available as a compatibility host during cutover, but new SDK docs and examples should not treat it as the long-term default.

Commands

• pnpm install --frozen-lockfile
• pnpm build
• pnpm test
• pnpm test:unit
• pnpm test:acceptance
• pnpm test:coverage
• pnpm api:validate
• pnpm api:postman
• pnpm auth:issuer:check
• pnpm dev
• pnpm docs:api:build
• pnpm docs:api:check
• pnpm lint
• pnpm typecheck
• pnpm deno:check:core
• pnpm check:core-package
• pnpm validate:yeet

For local build, validation, and smoke-style package checks, use pnpm install --frozen-lockfile so your dependency graph matches CI and Vercel instead of silently refreshing the lockfile.

For the full pre-PR and pre-yeet gate, run:

pnpm validate:yeet

pnpm auth:issuer:check is the metadata-only release-readiness gate for the production Identity issuer. It checks discovery, exact issuer equality, JWKS, authorization-code support, PKCE S256, and pairwise subject metadata without exchanging credentials or requiring a user login. It defaults to https://id.cubid.me and never falls back to staging. To probe staging explicitly, run:

pnpm auth:issuer:check -- --environment staging --issuer https://staging-id.cubid.me

Workflow

• dev is the main integration branch for ongoing SDK work.
• main is the release branch used for trusted npm and JSR publishing.
• Feature work should generally land on a feature branch, merge into dev, and then move to main when it is ready to publish.

Repo-health snapshots live in agent-context/repo-status.md. Deferred ideas that are not part of the active roadmap live in agent-context/future-ideas.md. The testing baseline and coverage policy live in docs/engineering/testing-strategy.md.

Supabase Edge / Deno

@cubid/core is the runtime-agnostic package in this workspace. It is the only Cubid package intended for direct use inside Deno and Supabase Edge Functions.

Use that package for first-class Deno imports:

import { createCubidApiClient } from "jsr:@cubid/core"

If a Deno environment cannot use JSR directly for some reason, it can still consume the same package through npm specifiers:

import { createCubidApiClient } from "npm:@cubid/core"

Node, Next.js, and other standard JS runtimes should continue to import the npm package directly:

import { createCubidApiClient } from "@cubid/core"

@cubid/auth, @cubid/auth-react, @cubid/aptos, @cubid/browser, @cubid/comms, @cubid/react, @cubid/bitcoin, @cubid/cosmos, @cubid/evm, @cubid/near, @cubid/polkadot, @cubid/solana, @cubid/starknet, @cubid/stellar, @cubid/sui, @cubid/tezos, @cubid/wagmi, @cubid/wallet-recovery, @cubid/wallet-recovery-react, and @cubid/web3 remain npm packages; they are not part of the JSR publication policy.