Session Management

The session system provides a unified way to handle different authentication methods:

• Secret Key NIP-01
• Nostr Extensions NIP-07
• Bunker URL NIP-46
• Amber or in-device NIP-55

while managing user state and encryption capabilities.

Overview

Sessions are stored in local storage and can be:

• Persisted across page reloads
• Used with multiple accounts
• Switched dynamically
• Backed by different signing methods

Basic Usage

import {ctx, setContext} from '@welshman/lib'
import {
  getDefaultNetContext,
  getDefaultAppContext,
  pubkey,
  sessions,
  session,
  addSession,
  getNip07
} from '@welshman/app'

// Set up app config
setContext({
  net: getDefaultNetContext(),
  app: getDefaultAppContext(),
})

// Log in via NIP-07 extension (browser wallet)
if (await getNip07()) {
  addSession({
    method: 'nip07',
    pubkey: await getNip07().getPublicKey()
  })
}

// Get current session
console.log(session.get()) // Current active session
console.log(pubkey.get()) // Current pubkey

Multiple Sessions

import {sessions, pubkey, addSession, dropSession} from '@welshman/app'

// Add multiple sessions
addSession({method: 'nip07', pubkey: 'abc...'})
addSession({method: 'nip46', pubkey: 'def...', secret: '123'})

// Switch between sessions
pubkey.set('abc...') // Activates that session

// Remove a session
dropSession('abc...')

// List all sessions
console.log(sessions.get())

NIP-46 (Bunker) Authentication

import {Nip46Broker, Nip46Signer} from '@welshman/signer'
import {addSession} from '@welshman/app'

// Connect to a bunker
const clientSecret = makeSecret()
const relays = ['wss://relay.damus.io']
const broker = Nip46Broker.get({relays, clientSecret})

// Generate nostrconnect URL for the bunker
const connectUrl = await broker.makeNostrconnectUrl({
  name: "My App",
  url: "https://myapp.com"
})

// Wait for user to approve in bunker
const response = await broker.waitForNostrconnect(connectUrl)

// Create session
addSession({
  method: 'nip46',
  pubkey: response.event.pubkey,
  secret: clientSecret,
  handler: {
    pubkey: response.event.pubkey,
    relays
  }
})

Using Session Signer

import {signer, session} from '@welshman/app'
import {createEvent, NOTE} from '@welshman/util'

// Current session's signer is always ready to use
const event = await signer.get().sign(
  createEvent(NOTE, {content: "Hello Nostr!"})
)

// Encrypt content for private notes
const encrypted = await signer.get().nip44.encrypt(
  pubkey,
  "Secret message"
)

Session Persistence

Sessions are automatically persisted to local storage. On page load:

import {pubkey, sessions} from '@welshman/app'

// Sessions load automatically from local storage
console.log(sessions.get()) // All stored sessions

// the current active session
console.log(session.get())

// Last active pubkey is restored
console.log(pubkey.get())

Session Types

type SessionNip07 = {
  method: "nip07"
  pubkey: string
}

type SessionNip46 = {
  method: "nip46"
  pubkey: string
  secret: string
  handler: {
    pubkey: string
    relays: string[]
  }
}

type SessionNip01 = {
  method: "nip01"
  pubkey: string
  secret: string
}

Error Handling

import {tryCatch} from '@welshman/lib'
import {addSession, getNip07} from '@welshman/app'

const login = async () => {
  const nip07 = await tryCatch(getNip07)

  if (!nip07) {
    throw new Error("No NIP-07 extension found")
  }

  const pubkey = await tryCatch(
    () => nip07.getPublicKey()
  )

  if (!pubkey) {
    throw new Error("Failed to get public key")
  }

  addSession({method: 'nip07', pubkey})
}