@lukso/core 1.2.10 → 1.2.11

package/dist/utils/index.d.ts

@@ -1,4 +1,5 @@
 import { DeviceService } from '../services/device.js';
+import { Hex } from 'viem';
 import 'ua-parser-js';
 
 type BrowserName = 'chrome' | 'safari' | 'firefox' | 'edge' | 'opera' | 'brave';
@@ -21,6 +22,206 @@ declare const EXTENSION_STORE_LINKS: {
  */
 declare const browserInfo: (deviceService: DeviceService) => BrowserInfo;
 
+/**
+ * @service-checkin/signed-qr-code
+ *
+ * Create and verify signed QR codes for Universal Profile check-ins.
+ * Pure TypeScript - compatible with React Native, Node.js, and browsers.
+ *
+ * URI Format: ethereum:<address>@<chainId>?ts=<unixTimestamp>&sig=<signature>
+ *
+ * The signed message is everything before &sig= (the URI without the signature).
+ * Uses EIP-191 prefixed signing (signMessage) for safety - this prevents
+ * signed messages from being confused with transaction hashes.
+ */
+
+/**
+ * Custom signer function type.
+ * Takes the message string and returns an EIP-191 signature.
+ * The signer should use `signMessage` (which adds the EIP-191 prefix).
+ * Compatible with hardware wallets, secure enclaves, WalletConnect, etc.
+ *
+ * The EIP-191 prefix prevents signed messages from being confused with
+ * transaction hashes, making this safe for identity verification.
+ */
+type SignerFunction = (message: string) => Promise<Hex>;
+interface CreateSignedQROptions {
+    /**
+     * Seconds to add to current time to account for QR generation/display latency.
+     * The QR timestamp will be set to (now + generationOffsetSeconds).
+     * Capped at 5 seconds maximum to prevent abuse.
+     * Default: 0
+     */
+    generationOffsetSeconds?: number;
+    /**
+     * Custom signer function for signing the message.
+     * If provided, the privateKey parameter can be omitted or set to null.
+     * Useful for hardware wallets, secure enclaves, or WalletConnect.
+     *
+     * The signer receives the message string and should use `signMessage`
+     * (EIP-191 prefixed signing) to return the signature.
+     *
+     * @example
+     * ```ts
+     * // Using a wallet that signs messages
+     * const uri = await createSignedQR(null, profileAddress, 42, {
+     *   signer: async (message) => {
+     *     return await wallet.signMessage(message)
+     *   }
+     * })
+     * ```
+     */
+    signer?: SignerFunction;
+}
+interface VerifySignedQROptions {
+    /** Maximum age in seconds before QR is considered expired (default: 60) */
+    maxAgeSeconds?: number;
+    /** Skip timestamp validation (useful for testing) */
+    skipTimestampValidation?: boolean;
+}
+interface VerificationResult {
+    /** Whether the QR code is valid and not expired */
+    isValid: boolean;
+    /** The Universal Profile address from the QR */
+    profileAddress: string;
+    /** The chain ID from the QR */
+    chainId: number;
+    /** The timestamp from the QR (unix seconds) */
+    timestamp: number;
+    /** The address recovered from the signature (the controller) */
+    recoveredAddress: string;
+    /** Whether the QR has expired based on maxAgeSeconds */
+    isExpired: boolean;
+    /** The original signed message (for EIP-1271 verification) */
+    message: string;
+    /** The hash of the message (for EIP-1271 verification) */
+    messageHash: Hex;
+}
+interface ParsedQRData {
+    profileAddress: string;
+    chainId: number;
+    timestamp: number;
+    signature: Hex;
+    message: string;
+}
+/**
+ * Create the message that will be signed.
+ * This is the URI without the signature parameter.
+ */
+declare function createMessage(profileAddress: string, chainId: number, timestamp: number): string;
+/**
+ * Create a signed QR URI string.
+ *
+ * @param privateKey - The controller's private key (hex string with 0x prefix).
+ *                     Can be '0x' or omitted if using options.signer.
+ * @param profileAddress - The Universal Profile address to sign for
+ * @param chainId - The chain ID (42 for LUKSO mainnet, 4201 for testnet)
+ * @param options - Optional configuration including custom signer
+ * @returns The complete signed URI string ready to encode as QR
+ *
+ * @example
+ * ```ts
+ * // Using a private key directly
+ * const uri = await createSignedQR(
+ *   '0x1234...', // controller private key
+ *   '0xabcd...', // profile address
+ *   42,          // LUKSO mainnet
+ *   { generationOffsetSeconds: 2 }
+ * )
+ *
+ * // Using a custom signer (WalletConnect, hardware wallet, etc.)
+ * const uri = await createSignedQR(
+ *   null,        // not needed when signer is provided
+ *   '0xabcd...', // profile address
+ *   42,          // LUKSO mainnet
+ *   {
+ *     signer: async (message) => await wallet.signMessage(message)
+ *   }
+ * )
+ * // Returns: ethereum:0xabcd...@42?ts=1706345678&sig=0x...
+ * ```
+ */
+declare function createSignedQR(privateKey: Hex | null, profileAddress: string, chainId: number, options?: CreateSignedQROptions): Promise<string>;
+/**
+ * Parse a signed QR URI without verification.
+ * Use this when you need to extract data before full verification.
+ *
+ * @param uri - The signed QR URI string
+ * @returns Parsed data or null if format is invalid
+ */
+declare function parseSignedQR(uri: string): ParsedQRData | null;
+/**
+ * Verify a signed QR URI and recover the signer.
+ *
+ * This performs:
+ * 1. URI format validation
+ * 2. Signature recovery (gets the controller address that signed)
+ * 3. Timestamp validation (checks if expired)
+ *
+ * Note: This does NOT verify that the recovered address is an authorized
+ * controller of the profile. That check should be done separately using
+ * EIP-1271 isValidSignature() or by checking controller permissions on-chain.
+ *
+ * @param uri - The signed QR URI string
+ * @param options - Optional configuration
+ * @returns Verification result with recovered address
+ *
+ * @example
+ * ```ts
+ * const result = await verifySignedQR(uri)
+ *
+ * if (result.isValid) {
+ *   console.log('Profile:', result.profileAddress)
+ *   console.log('Signed by:', result.recoveredAddress)
+ *
+ *   // Now verify the signer is an authorized controller
+ *   // Option 1: Check if recoveredAddress === profileAddress (EOA case)
+ *   // Option 2: Call isValidSignature() on the profile contract
+ * }
+ * ```
+ */
+declare function verifySignedQR(uri: string, options?: VerifySignedQROptions): Promise<VerificationResult>;
+/**
+ * Check if a string looks like a valid signed QR URI.
+ * This is a quick format check without full verification.
+ */
+declare function isSignedQRFormat(uri: string): boolean;
+/**
+ * Get the controller address from a private key.
+ * Useful for displaying which address will sign the QR codes.
+ */
+declare function getControllerAddress(privateKey: Hex): string;
+/**
+ * EIP-1271 magic value returned for valid signatures
+ */
+declare const EIP1271_MAGIC_VALUE: "0x1626ba7e";
+/**
+ * Prepare data for EIP-1271 verification.
+ * Returns the hash and signature needed to call isValidSignature().
+ *
+ * @param uri - The original signed QR URI (needed to extract the signature)
+ * @param verificationResult - The result from verifySignedQR()
+ *
+ * @example
+ * ```ts
+ * const result = await verifySignedQR(uri)
+ * const { hash, signature } = getEIP1271Data(uri, result)
+ *
+ * const magicValue = await client.readContract({
+ *   address: result.profileAddress,
+ *   abi: EIP1271_ABI,
+ *   functionName: 'isValidSignature',
+ *   args: [hash, signature],
+ * })
+ *
+ * const isAuthorizedController = magicValue === EIP1271_MAGIC_VALUE
+ * ```
+ */
+declare function getEIP1271Data(uri: string, verificationResult: VerificationResult): {
+    hash: Hex;
+    signature: Hex;
+};
+
 /**
  * Make slug from text
  *
@@ -62,4 +263,4 @@ declare class UrlResolver {
     resolveUrl(url_: string): string;
 }
 
-export { type BrowserInfo, type BrowserName, EXTENSION_STORE_LINKS, UrlConverter, UrlResolver, browserInfo, slug };
+export { type BrowserInfo, type BrowserName, EIP1271_MAGIC_VALUE, EXTENSION_STORE_LINKS, UrlConverter, UrlResolver, browserInfo, createMessage, createSignedQR, getControllerAddress, getEIP1271Data, isSignedQRFormat, parseSignedQR, slug, verifySignedQR };

package/dist/utils/index.js

@@ -1,16 +1,32 @@
 import {
+  EIP1271_MAGIC_VALUE,
   EXTENSION_STORE_LINKS,
   UrlConverter,
   UrlResolver,
   browserInfo,
-  slug
-} from "../chunk-GFLV5EJV.js";
+  createMessage,
+  createSignedQR,
+  getControllerAddress,
+  getEIP1271Data,
+  isSignedQRFormat,
+  parseSignedQR,
+  slug,
+  verifySignedQR
+} from "../chunk-RECO5F6T.js";
 import "../chunk-ET7EYHRY.js";
 export {
+  EIP1271_MAGIC_VALUE,
   EXTENSION_STORE_LINKS,
   UrlConverter,
   UrlResolver,
   browserInfo,
-  slug
+  createMessage,
+  createSignedQR,
+  getControllerAddress,
+  getEIP1271Data,
+  isSignedQRFormat,
+  parseSignedQR,
+  slug,
+  verifySignedQR
 };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukso/core",
-  "version": "1.2.10",
+  "version": "1.2.11",
   "description": "Core utilities, services, and mixins for LUKSO web components and applications",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/utils/__tests__/signed-profile-urls.spec.ts

@@ -0,0 +1,276 @@
+import type { Hex } from 'viem'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  createMessage,
+  createSignedQR,
+  EIP1271_MAGIC_VALUE,
+  getControllerAddress,
+  getEIP1271Data,
+  isSignedQRFormat,
+  parseSignedQR,
+  verifySignedQR,
+} from '../signed-profile-urls.js'
+
+describe('signed-qr-code', () => {
+  let privateKey: Hex
+  const profileAddress = '0x1234567890123456789012345678901234567890'
+  const chainId = 42
+
+  beforeEach(() => {
+    privateKey = generatePrivateKey()
+    // Mock Date.now for consistent timestamps in tests
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2024-01-27T12:00:00Z'))
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  describe('createMessage', () => {
+    it('creates a deterministic message', () => {
+      const message = createMessage(profileAddress, chainId, 1706356800)
+      expect(message).toBe(
+        'ethereum:0x1234567890123456789012345678901234567890@42?ts=1706356800'
+      )
+    })
+
+    it('lowercases the address', () => {
+      const message = createMessage(
+        '0xABCDEF1234567890123456789012345678901234',
+        chainId,
+        1706356800
+      )
+      expect(message).toContain('0xabcdef1234567890123456789012345678901234')
+    })
+  })
+
+  describe('createSignedQR', () => {
+    it('creates a valid signed URI', async () => {
+      const uri = await createSignedQR(privateKey, profileAddress, chainId)
+
+      expect(uri).toMatch(
+        /^ethereum:0x[a-f0-9]{40}@\d+\?ts=\d+&sig=0x[a-f0-9]+$/
+      )
+    })
+
+    it('uses current timestamp by default (no offset)', async () => {
+      const uri = await createSignedQR(privateKey, profileAddress, chainId)
+      const parsed = parseSignedQR(uri)
+
+      const now = Math.floor(Date.now() / 1000)
+      expect(parsed?.timestamp).toBe(now) // default offset is 0
+    })
+
+    it('respects generationOffsetSeconds option', async () => {
+      const uri = await createSignedQR(privateKey, profileAddress, chainId, {
+        generationOffsetSeconds: 3,
+      })
+      const parsed = parseSignedQR(uri)
+
+      const now = Math.floor(Date.now() / 1000)
+      expect(parsed?.timestamp).toBe(now + 3)
+    })
+
+    it('caps generationOffsetSeconds at 5 seconds', async () => {
+      const uri = await createSignedQR(privateKey, profileAddress, chainId, {
+        generationOffsetSeconds: 100, // way over the limit
+      })
+      const parsed = parseSignedQR(uri)
+
+      const now = Math.floor(Date.now() / 1000)
+      expect(parsed?.timestamp).toBe(now + 5) // capped at 5
+    })
+
+    it('does not allow negative generationOffsetSeconds', async () => {
+      const uri = await createSignedQR(privateKey, profileAddress, chainId, {
+        generationOffsetSeconds: -10,
+      })
+      const parsed = parseSignedQR(uri)
+
+      const now = Math.floor(Date.now() / 1000)
+      expect(parsed?.timestamp).toBe(now) // clamped to 0
+    })
+
+    it('uses custom signer when provided', async () => {
+      const controllerAddress = getControllerAddress(privateKey)
+
+      // Create a custom signer that uses signMessage (EIP-191)
+      const customSigner = async (message: string) => {
+        const account = privateKeyToAccount(privateKey)
+        return account.signMessage({ message })
+      }
+
+      const uri = await createSignedQR(null, profileAddress, chainId, {
+        signer: customSigner,
+      })
+
+      const result = await verifySignedQR(uri)
+      expect(result.isValid).toBe(true)
+      expect(result.recoveredAddress).toBe(controllerAddress.toLowerCase())
+    })
+
+    it('throws when neither privateKey nor signer is provided', async () => {
+      await expect(
+        createSignedQR(null, profileAddress, chainId)
+      ).rejects.toThrow(
+        'Either a valid privateKey or options.signer must be provided'
+      )
+    })
+
+    it('throws when privateKey is 0x and no signer provided', async () => {
+      await expect(
+        createSignedQR('0x', profileAddress, chainId)
+      ).rejects.toThrow(
+        'Either a valid privateKey or options.signer must be provided'
+      )
+    })
+  })
+
+  describe('parseSignedQR', () => {
+    it('parses a valid URI', async () => {
+      const uri = await createSignedQR(privateKey, profileAddress, chainId)
+      const parsed = parseSignedQR(uri)
+
+      expect(parsed).not.toBeNull()
+      expect(parsed?.profileAddress).toBe(profileAddress.toLowerCase())
+      expect(parsed?.chainId).toBe(chainId)
+      expect(parsed?.signature).toMatch(/^0x[a-f0-9]+$/)
+    })
+
+    it('returns null for invalid format', () => {
+      expect(parseSignedQR('invalid')).toBeNull()
+      expect(parseSignedQR('ethereum:invalid')).toBeNull()
+      expect(parseSignedQR('http://example.com')).toBeNull()
+    })
+
+    it('returns null for missing signature', () => {
+      expect(
+        parseSignedQR(
+          'ethereum:0x1234567890123456789012345678901234567890@42?ts=123'
+        )
+      ).toBeNull()
+    })
+  })
+
+  describe('verifySignedQR', () => {
+    it('verifies a freshly created QR', async () => {
+      const uri = await createSignedQR(privateKey, profileAddress, chainId, {
+        generationOffsetSeconds: 0,
+      })
+      const result = await verifySignedQR(uri)
+
+      expect(result.isValid).toBe(true)
+      expect(result.isExpired).toBe(false)
+      expect(result.profileAddress).toBe(profileAddress.toLowerCase())
+      expect(result.chainId).toBe(chainId)
+    })
+
+    it('recovers the correct controller address', async () => {
+      const controllerAddress = getControllerAddress(privateKey)
+      const uri = await createSignedQR(privateKey, profileAddress, chainId)
+      const result = await verifySignedQR(uri)
+
+      expect(result.recoveredAddress).toBe(controllerAddress.toLowerCase())
+    })
+
+    it('marks expired QR as invalid', async () => {
+      // Create a QR at current time
+      const uri = await createSignedQR(privateKey, profileAddress, chainId)
+
+      // Advance time by 2 minutes (past the 60 second maxAge)
+      vi.advanceTimersByTime(120 * 1000)
+
+      const result = await verifySignedQR(uri, { maxAgeSeconds: 60 })
+
+      expect(result.isValid).toBe(false)
+      expect(result.isExpired).toBe(true)
+    })
+
+    it('allows skipping timestamp validation', async () => {
+      // Create a QR at current time
+      const uri = await createSignedQR(privateKey, profileAddress, chainId)
+
+      // Advance time by 2 minutes (would normally be expired)
+      vi.advanceTimersByTime(120 * 1000)
+
+      const result = await verifySignedQR(uri, {
+        skipTimestampValidation: true,
+      })
+
+      expect(result.isValid).toBe(true)
+      expect(result.isExpired).toBe(false)
+    })
+
+    it('throws for invalid URI format', async () => {
+      await expect(verifySignedQR('invalid')).rejects.toThrow(
+        'Invalid QR format'
+      )
+    })
+  })
+
+  describe('isSignedQRFormat', () => {
+    it('returns true for valid format', async () => {
+      const uri = await createSignedQR(privateKey, profileAddress, chainId)
+      expect(isSignedQRFormat(uri)).toBe(true)
+    })
+
+    it('returns false for invalid formats', () => {
+      expect(isSignedQRFormat('invalid')).toBe(false)
+      expect(isSignedQRFormat('ethereum:0x123')).toBe(false)
+      expect(isSignedQRFormat('http://example.com')).toBe(false)
+    })
+  })
+
+  describe('getControllerAddress', () => {
+    it('returns the address for a private key', () => {
+      const address = getControllerAddress(privateKey)
+      expect(address).toMatch(/^0x[a-fA-F0-9]{40}$/)
+    })
+  })
+
+  describe('getEIP1271Data', () => {
+    it('returns hash and signature for EIP-1271 verification', async () => {
+      const uri = await createSignedQR(privateKey, profileAddress, chainId)
+      const result = await verifySignedQR(uri)
+      const { hash, signature } = getEIP1271Data(uri, result)
+
+      expect(hash).toMatch(/^0x[a-f0-9]{64}$/)
+      expect(signature).toMatch(/^0x[a-f0-9]+$/)
+      expect(hash).toBe(result.messageHash)
+    })
+  })
+
+  describe('EIP1271_MAGIC_VALUE', () => {
+    it('is the correct magic value', () => {
+      expect(EIP1271_MAGIC_VALUE).toBe('0x1626ba7e')
+    })
+  })
+
+  describe('round-trip verification', () => {
+    it('creates and verifies QR for different chain IDs', async () => {
+      for (const testChainId of [42, 4201, 1]) {
+        const uri = await createSignedQR(
+          privateKey,
+          profileAddress,
+          testChainId,
+          { generationOffsetSeconds: 0 }
+        )
+        const result = await verifySignedQR(uri)
+
+        expect(result.isValid).toBe(true)
+        expect(result.chainId).toBe(testChainId)
+      }
+    })
+
+    it('signature is deterministic for same inputs', async () => {
+      // With the same timestamp, the signature should be the same
+      const timestamp = Math.floor(Date.now() / 1000)
+      const message1 = createMessage(profileAddress, chainId, timestamp)
+      const message2 = createMessage(profileAddress, chainId, timestamp)
+
+      expect(message1).toBe(message2)
+    })
+  })
+})

package/src/utils/index.ts

@@ -1,5 +1,14 @@
 export type { BrowserInfo, BrowserName } from './browserInfo.js'
 export { browserInfo, EXTENSION_STORE_LINKS } from './browserInfo.js'
-
+export {
+  createMessage,
+  createSignedQR,
+  EIP1271_MAGIC_VALUE,
+  getControllerAddress,
+  getEIP1271Data,
+  isSignedQRFormat,
+  parseSignedQR,
+  verifySignedQR,
+} from './signed-profile-urls.js'
 export { slug } from './slug.js'
 export { UrlConverter, UrlResolver } from './url-resolver.js'