@stacks-passkey/relay 0.1.0

package/dist/wallet-auth.d.ts

@@ -0,0 +1,43 @@
+import type { RelayConfig } from './types.js';
+export declare function relayAuthDomain(network: RelayConfig['network']): import("@stacks/transactions").TupleCV<import("@stacks/transactions").TupleData<import("@stacks/transactions").UIntCV | import("@stacks/transactions").StringAsciiCV>>;
+export declare function buildAuthMessage(address: string, nonce: string, expiresAt: number): import("@stacks/transactions").TupleCV<import("@stacks/transactions").TupleData<import("@stacks/transactions").UIntCV | import("@stacks/transactions").StringAsciiCV>>;
+export declare function buildPlainAuthMessage(address: string, nonce: string, expiresAt: number): string;
+export declare function issueAuthChallengeForNetwork(address: string, network: RelayConfig['network']): {
+    nonce: string;
+    expiresAt: number;
+    plainMessage: string;
+    domain: import("@stacks/transactions").TupleCV<import("@stacks/transactions").TupleData<import("@stacks/transactions").UIntCV | import("@stacks/transactions").StringAsciiCV>>;
+    message: import("@stacks/transactions").TupleCV<import("@stacks/transactions").TupleData<import("@stacks/transactions").UIntCV | import("@stacks/transactions").StringAsciiCV>>;
+};
+export type AuthVerifyFailure = 'missing_challenge' | 'nonce_mismatch' | 'expires_mismatch' | 'expired' | 'bad_signature';
+export declare function verifyAuthSignatureWithReason(opts: {
+    address: string;
+    signature: string;
+    publicKey: string;
+    nonce: string;
+    expiresAt: number;
+    network: RelayConfig['network'];
+    mode?: 'structured' | 'plain';
+    plainMessage?: string;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: AuthVerifyFailure;
+};
+export declare function verifyAuthSignature(opts: {
+    address: string;
+    signature: string;
+    publicKey: string;
+    nonce: string;
+    expiresAt: number;
+    network: RelayConfig['network'];
+    mode?: 'structured' | 'plain';
+    plainMessage?: string;
+}): boolean;
+export declare function createWalletSession(address: string, sessionSecret: string): {
+    sessionToken: string;
+    expiresAt: number;
+};
+/** @internal test helper */
+export declare function clearAuthChallenges(): void;

package/dist/wallet-auth.js

@@ -0,0 +1,145 @@
+import { randomBytes } from 'node:crypto';
+import { Cl, encodeStructuredDataBytes, getAddressFromPublicKey, publicKeyFromSignatureRsv, } from '@stacks/transactions';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex, concatBytes, utf8ToBytes } from '@stacks/common';
+import { createSessionToken } from './crypto.js';
+const CHALLENGE_TTL_MS = 5 * 60 * 1000;
+const pendingChallenges = new Map();
+function chainIdForNetwork(network) {
+    return network === 'mainnet' ? 1 : 0x80000000;
+}
+export function relayAuthDomain(network) {
+    const domainName = process.env.RELAY_AUTH_DOMAIN ?? 'localhost';
+    return Cl.tuple({
+        name: Cl.stringAscii(domainName),
+        version: Cl.stringAscii('1.0.0'),
+        'chain-id': Cl.uint(chainIdForNetwork(network)),
+    });
+}
+export function buildAuthMessage(address, nonce, expiresAt) {
+    return Cl.tuple({
+        action: Cl.stringAscii('authenticate'),
+        address: Cl.stringAscii(address),
+        nonce: Cl.stringAscii(nonce),
+        expires: Cl.uint(expiresAt),
+    });
+}
+export function buildPlainAuthMessage(address, nonce, expiresAt) {
+    return [
+        'Stacks Passkey Relay Login',
+        `address=${address}`,
+        `nonce=${nonce}`,
+        `expires=${expiresAt}`,
+    ].join('\n');
+}
+export function issueAuthChallengeForNetwork(address, network) {
+    const nonce = randomBytes(16).toString('hex');
+    const expiresAt = Date.now() + CHALLENGE_TTL_MS;
+    pendingChallenges.set(address, { nonce, expiresAt });
+    return {
+        nonce,
+        expiresAt,
+        plainMessage: buildPlainAuthMessage(address, nonce, expiresAt),
+        domain: relayAuthDomain(network),
+        message: buildAuthMessage(address, nonce, expiresAt),
+    };
+}
+function hashPlainMessage(message) {
+    const bytes = utf8ToBytes(message);
+    const hashes = [bytesToHex(sha256(bytes))];
+    // Leather / SIWS plain signing uses \x17Stacks Signed Message:\n
+    const siwsPrefix = '\x17Stacks Signed Message:\n';
+    const siwsPrefixed = concatBytes(utf8ToBytes(siwsPrefix), utf8ToBytes(String(bytes.length)), bytes);
+    hashes.push(bytesToHex(sha256(siwsPrefixed)));
+    // Legacy alternate prefix (keep for compatibility)
+    const legacyPrefix = '\x18Stacks Message Signing:\n';
+    const legacyPrefixed = concatBytes(utf8ToBytes(legacyPrefix), utf8ToBytes(String(bytes.length)), bytes);
+    hashes.push(bytesToHex(sha256(legacyPrefixed)));
+    return hashes;
+}
+function verifyPlainSignature(opts) {
+    const sig = opts.signature.startsWith('0x') ? opts.signature.slice(2) : opts.signature;
+    const networkName = opts.network === 'mainnet' ? 'mainnet' : 'testnet';
+    for (const messageHash of hashPlainMessage(opts.message)) {
+        try {
+            const recovered = publicKeyFromSignatureRsv(messageHash, sig);
+            const recoveredAddress = getAddressFromPublicKey(recovered, networkName);
+            if (recoveredAddress !== opts.address)
+                continue;
+            const providedAddress = getAddressFromPublicKey(opts.publicKey.startsWith('0x') ? opts.publicKey.slice(2) : opts.publicKey, networkName);
+            if (providedAddress === opts.address)
+                return true;
+        }
+        catch {
+            // try next hash format
+        }
+    }
+    return false;
+}
+function verifyStructuredSignature(opts) {
+    const structuredHash = bytesToHex(sha256(encodeStructuredDataBytes({ message: opts.message, domain: opts.domain })));
+    const sig = opts.signature.startsWith('0x') ? opts.signature.slice(2) : opts.signature;
+    const recovered = publicKeyFromSignatureRsv(structuredHash, sig);
+    const recoveredAddress = getAddressFromPublicKey(recovered, opts.network === 'mainnet' ? 'mainnet' : 'testnet');
+    if (recoveredAddress !== opts.address)
+        return false;
+    const providedAddress = getAddressFromPublicKey(opts.publicKey.startsWith('0x') ? opts.publicKey.slice(2) : opts.publicKey, opts.network === 'mainnet' ? 'mainnet' : 'testnet');
+    return providedAddress === opts.address;
+}
+export function verifyAuthSignatureWithReason(opts) {
+    const pending = pendingChallenges.get(opts.address);
+    if (!pending)
+        return { ok: false, reason: 'missing_challenge' };
+    if (pending.nonce !== opts.nonce)
+        return { ok: false, reason: 'nonce_mismatch' };
+    if (pending.expiresAt !== opts.expiresAt)
+        return { ok: false, reason: 'expires_mismatch' };
+    if (Date.now() > pending.expiresAt) {
+        pendingChallenges.delete(opts.address);
+        return { ok: false, reason: 'expired' };
+    }
+    const mode = opts.mode ?? 'structured';
+    let ok = false;
+    if (mode === 'plain') {
+        const message = opts.plainMessage ?? buildPlainAuthMessage(opts.address, opts.nonce, opts.expiresAt);
+        ok = verifyPlainSignature({
+            address: opts.address,
+            signature: opts.signature,
+            publicKey: opts.publicKey,
+            message,
+            network: opts.network,
+        });
+    }
+    else {
+        const domain = relayAuthDomain(opts.network);
+        const message = buildAuthMessage(opts.address, opts.nonce, opts.expiresAt);
+        ok = verifyStructuredSignature({
+            address: opts.address,
+            signature: opts.signature,
+            publicKey: opts.publicKey,
+            message,
+            domain,
+            network: opts.network,
+        });
+    }
+    if (ok) {
+        pendingChallenges.delete(opts.address);
+        return { ok: true };
+    }
+    return { ok: false, reason: 'bad_signature' };
+}
+export function verifyAuthSignature(opts) {
+    return verifyAuthSignatureWithReason(opts).ok;
+}
+export function createWalletSession(address, sessionSecret) {
+    const ttlMs = Number(process.env.RELAY_SESSION_TTL_MS ?? `${24 * 60 * 60 * 1000}`);
+    const expiresAt = Date.now() + ttlMs;
+    return {
+        sessionToken: createSessionToken(address, sessionSecret, ttlMs),
+        expiresAt,
+    };
+}
+/** @internal test helper */
+export function clearAuthChallenges() {
+    pendingChallenges.clear();
+}

package/dist/wallet-auth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/wallet-auth.test.js

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { buildPlainAuthMessage, clearAuthChallenges, issueAuthChallengeForNetwork, verifyAuthSignature, } from './wallet-auth.js';
+import { privateKeyToAddress, privateKeyToPublic, signMessageHashRsv } from '@stacks/transactions';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex, concatBytes, utf8ToBytes } from '@stacks/common';
+describe('wallet-auth plain signatures', () => {
+    it('accepts SIWS-style plain message signatures (Leather stx_signMessage)', () => {
+        clearAuthChallenges();
+        const privateKey = 'f5a31c1268a1e37d4edaa05c7d11183c5fbfdcdc48aae36ea4d8cd5cb709932801';
+        const publicKey = privateKeyToPublic(privateKey);
+        const address = privateKeyToAddress(privateKey, 'testnet');
+        const { nonce, expiresAt } = issueAuthChallengeForNetwork(address, 'testnet');
+        const plainMessage = buildPlainAuthMessage(address, nonce, expiresAt);
+        const bytes = utf8ToBytes(plainMessage);
+        const prefixed = concatBytes(utf8ToBytes('\x17Stacks Signed Message:\n'), utf8ToBytes(String(bytes.length)), bytes);
+        const messageHash = bytesToHex(sha256(prefixed));
+        const signature = signMessageHashRsv({ messageHash, privateKey });
+        const ok = verifyAuthSignature({
+            address,
+            signature,
+            publicKey,
+            nonce,
+            expiresAt,
+            network: 'testnet',
+            mode: 'plain',
+            plainMessage,
+        });
+        expect(ok).toBe(true);
+    });
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@stacks-passkey/relay",
+  "version": "0.1.0",
+  "description": "Self-hostable sponsored transaction relay for Stacks Passkey SDK",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "stacks-passkey-relay": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/cli.ts",
+    "start": "node dist/cli.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@stacks/network": "^7.0.2",
+    "@stacks/transactions": "^7.0.2",
+    "hono": "^4.6.14"
+  },
+  "devDependencies": {
+    "@hono/node-server": "^1.13.7",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5"
+  },
+  "keywords": [
+    "stacks",
+    "passkey",
+    "relay",
+    "sponsor"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Stacks-utils/stacks-passkey-sdk.git",
+    "directory": "packages/relay"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}