selfy

Type definitions for the Selfy Protocol - A standardized protocol for passkey-based self-custody wallets.

Installation

npm install selfy

Usage

Basic QR Code Flow

import type { QrCodeData, WebhookPayload } from 'selfy';

// App generates QR code
const qrData: QrCodeData = {
  signMessage: 'base58EncodedMessage',
  algorithm: 'p256',
  webhookUrl: 'https://app.example.com/webhook'
};

// Wallet sends webhook
const payload: WebhookPayload = {
  signature: 'userPasskeySignature',
  algorithm: 'p256',
  walletSignature: 'optionalWalletOperatorSignature',
  walletPublicKey: 'optionalWalletOperatorPublicKey'
};

Sign-In with Selfy (SIWS)

import { formatSelfyMessage, type SelfyMessage } from 'selfy';
import { encodeBase58 } from 'your-base58-library';

// Create a SIWS message
const message: SelfyMessage = {
  domain: 'app.example.com',
  walletId: '0x1234...abcd',
  statement: 'Sign in to access your account',
  uri: 'https://app.example.com',
  version: '1',
  nonce: '32891756',
  issuedAt: new Date().toISOString(),
  expirationTime: new Date(Date.now() + 3600000).toISOString() // 1 hour
};

// Format the message
const formattedMessage = formatSelfyMessage(message);

// Encode for QR code
const qrData: QrCodeData = {
  signMessage: encodeBase58(formattedMessage),
  algorithm: 'p256',
  webhookUrl: 'https://app.example.com/auth/callback'
};

Protocol Overview

1. Apps display a QR code containing transaction data
2. Wallets scan the QR code and sign with user's passkey
3. Wallets send the signature to the app's webhook URL
4. Apps can optionally require wallet operator signatures for compliance

Type Definitions

QrCodeData

The QR code format that apps should generate:

• signMessage: Base58 encoded message to be signed
• algorithm: Signature algorithm (currently only 'p256')
• webhookUrl: URL where the wallet will send the signature

WebhookPayload

The payload that wallets send to apps:

• signature: User's passkey signature
• algorithm: Signature algorithm used
• walletSignature: Optional wallet operator signature
• walletPublicKey: Optional wallet operator public key

SelfyMessage

Structured message format for Sign-In with Selfy:

• domain: The domain requesting the signature
• walletId: User's wallet identifier
• statement: Human-readable purpose
• uri: The URI of the requesting application
• version: Message format version
• nonce: Random value to prevent replay attacks
• issuedAt: ISO 8601 datetime when created
• expirationTime: Optional expiration datetime

Reference Implementation

See the full reference implementation at: https://github.com/sunriselayer/selfy

License

Apache 2.0