SessionKit docs

API reference

Everything @blaclabs/sessionkit exports, in both halves — browser and server.

Browser

connect(options)

Generates a session key pair, has your server sign the request, renders the BLAC Code, and resolves once the user approves in BLAC Wallet.

OptionTypeMeaning
scopes Scope[] What you're asking for. identity is added automatically. Required.
sign (fields) => Promise Sends the request fields to your backend and returns its signature. Required.
mount HTMLElement Where to draw the code. A canvas is created inside it. Omit to render the code yourself.
origin string Defaults to the page's origin. Must match your well-known document.
appId string Your app identifier. Defaults to the origin's hostname.
expirySeconds number Code lifetime. Capped at 180.
render { color, background } Code colours. Keep the strokes light on a dark card.
signal AbortSignal Cancel the pending sign-in (user closed your modal).

The session object

{
  origin: "https://your-domain.com",
  grantedScopes: ["identity", "address:solana"],
  user: {
    id: "…",           // pairwise, stable, unique to your origin
    pubKey: "…",       // Ed25519 public key
    proof: "…",        // signature binding this login to this session
    username?: "…",        // iff profile:username granted
    avatar?: "…",          // iff profile:avatar granted (base64)
    avatarMimeType?: "…",
    solanaAddress?: "…",   // iff address:solana granted
    favoriteMarkets?: […]  // iff favorites:read granted
  },
  raw: { … }           // forward this to your backend to verify
}

Fields for scopes that were not granted are absent, not null. Always check before use — the user may approve some scopes and not others.

Errors

Failures throw a SessionError with a code you can branch on:

CodeMeaning
invalid_scope You requested a scope outside the third-party catalog.
signing_failed Your sign callback threw or returned nothing.
relay_unavailable The relay could not be reached. Offer a retry.
expired Nobody scanned in time. Generate a new code.
invalid_response The approval failed verification. Treat as hostile: never log the user in.
aborted Your AbortSignal fired.

Rendering the code yourself

Skip mount and draw it where you like. Geometry is on a 440×440 logical canvas. 

import { renderBlacCode, blacCodeGeometry } from "@blaclabs/sessionkit";

renderBlacCode(canvas, pairingTopic, { color: "#fff" });

// or build your own SVG / WebGL / print output
const { data, anchors } = blacCodeGeometry(pairingTopic);

Server

Imported from @blaclabs/sessionkit/server. Node only — never import this from browser code.

signSessionRequest({ fields, privateKeyPem, kid })

Signs the request fields with your Ed25519 domain key and returns { sig, sigKid }. Validate that fields.origin is your own origin before signing — your signing endpoint is the one thing that must never sign for someone else.

verifyApproval({ approval, origin, pairingTopic })

Verifies a completed login and returns { userId, origin, grantedScopes, username?, solanaAddress? }. Throws if the proof, the origin, or the user id fails to check out. No network call — the proof is self-contained.

Types

import type {
  Scope, Session, ApprovedUser, SessionError, ConnectOptions
} from "@blaclabs/sessionkit";