@stacks-passkey/relay 0.1.0

package/dist/catalog.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { CatalogStore } from './catalog.js';
+describe('CatalogStore', () => {
+    let dir;
+    let store;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'spk-catalog-'));
+        store = new CatalogStore(join(dir, 'catalog.json'));
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it('saves and lists contracts per project', () => {
+        store.save({
+            contractId: 'ST1PQ.my-app',
+            projectId: 'proj-1',
+            functions: ['passkey-exec', 'set-score'],
+            registeredAt: new Date().toISOString(),
+            registrationTxid: 'abc123',
+        });
+        const list = store.listForProject('proj-1');
+        expect(list).toHaveLength(1);
+        expect(list[0]?.contractId).toBe('ST1PQ.my-app');
+    });
+    it('finds cached registration', () => {
+        store.save({
+            contractId: 'ST1PQ.my-app',
+            projectId: 'proj-1',
+            functions: ['passkey-exec'],
+            registeredAt: new Date().toISOString(),
+            registrationTxid: 'abc123',
+        });
+        const found = store.find('proj-1', 'ST1PQ.my-app');
+        expect(found?.registrationTxid).toBe('abc123');
+    });
+});

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { serve } from '@hono/node-server';
+import { createRelayApp } from './app.js';
+import { loadRelayEnv } from './load-env.js';
+import { assertRelayAuthConfigured, loadSponsorPrivateKey } from './secrets.js';
+import { GasTankStore, defaultStorePath } from './gas-tank.js';
+import { loadMasterSecret, loadSessionSecret } from './crypto.js';
+loadRelayEnv();
+function loadConfig() {
+    const network = process.env.STACKS_NETWORK ?? 'testnet';
+    assertRelayAuthConfigured(network);
+    return {
+        sponsorPrivateKey: loadSponsorPrivateKey(),
+        registrarPrivateKey: process.env.REGISTRAR_PRIVATE_KEY,
+        masterSecret: loadMasterSecret(),
+        sessionSecret: loadSessionSecret(),
+        network,
+        port: Number(process.env.PORT ?? 8787),
+        host: process.env.HOST ?? '127.0.0.1',
+        apiKey: process.env.RELAY_API_KEY,
+        adminApiKey: process.env.RELAY_ADMIN_API_KEY,
+        gasTankPath: process.env.GAS_TANK_PATH ?? defaultStorePath(),
+        policy: {
+            allowedContracts: process.env.ALLOWED_CONTRACTS?.split(',').filter(Boolean),
+            maxFeeMicroStx: BigInt(process.env.MAX_FEE_MICRO_STX ?? '100000'),
+            rateLimit: {
+                windowMs: Number(process.env.RATE_LIMIT_WINDOW_MS ?? '60000'),
+                maxRequests: Number(process.env.RATE_LIMIT_MAX ?? '30'),
+            },
+        },
+    };
+}
+const config = loadConfig();
+const sponsorNetwork = config.network === 'mainnet' ? 'mainnet' : 'testnet';
+const gasTank = new GasTankStore(config.gasTankPath, config.masterSecret, sponsorNetwork);
+const app = createRelayApp(config, gasTank);
+serve({ fetch: app.fetch, port: config.port, hostname: config.host }, () => {
+    console.log(`Stacks Passkey relay listening on http://${config.host}:${config.port}`);
+    console.log(`Relay store: ${config.gasTankPath}`);
+    console.log(`Registrar: ${config.network} (platform key — per-wallet sponsors derived from RELAY_MASTER_SECRET)`);
+});

package/dist/contract-id.d.ts

@@ -0,0 +1,2 @@
+import { type PayloadWire } from '@stacks/transactions';
+export declare function extractContractCallId(payload: PayloadWire): string | null;

package/dist/contract-id.js

@@ -0,0 +1,6 @@
+import { addressToString, isContractCallPayload, } from '@stacks/transactions';
+export function extractContractCallId(payload) {
+    if (!isContractCallPayload(payload))
+        return null;
+    return `${addressToString(payload.contractAddress)}.${payload.contractName.content}`;
+}

package/dist/contract-id.test.d.ts

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

package/dist/contract-id.test.js

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { Cl, makeContractCall, randomPrivateKey } from '@stacks/transactions';
+import { extractContractCallId } from './contract-id.js';
+import { isContractAllowed } from './rate-limit.js';
+describe('extractContractCallId', () => {
+    it('extracts a string contract id from deserialized contract-call payloads', async () => {
+        const tx = await makeContractCall({
+            contractAddress: 'ST3XHHZ1CXVCNYXK3FQ1FDGJ9NK6YBJBJK3FVY5KQ',
+            contractName: 'passkey-account-v2',
+            functionName: 'register',
+            functionArgs: [Cl.buffer(new Uint8Array(33).fill(2))],
+            senderKey: randomPrivateKey(),
+            sponsored: true,
+            fee: 0n,
+            network: 'testnet',
+        });
+        const contractId = extractContractCallId(tx.payload);
+        expect(contractId).toBe('ST3XHHZ1CXVCNYXK3FQ1FDGJ9NK6YBJBJK3FVY5KQ.passkey-account-v2');
+        expect(isContractAllowed(contractId, {
+            allowedContracts: ['ST3XHHZ1CXVCNYXK3FQ1FDGJ9NK6YBJBJK3FVY5KQ'],
+            maxFeeMicroStx: 50000n,
+            rateLimit: { windowMs: 60_000, maxRequests: 100 },
+        })).toBe(true);
+    });
+});

package/dist/crypto.d.ts

@@ -0,0 +1,9 @@
+export declare function hashApiKey(apiKey: string): string;
+export declare function generateApiKey(): string;
+export declare function apiKeyPrefix(apiKey: string): string;
+export declare function createSessionToken(address: string, secret: string, ttlMs?: number): string;
+export declare function verifySessionToken(token: string, secret: string): {
+    address: string;
+} | null;
+export declare function loadMasterSecret(): string;
+export declare function loadSessionSecret(): string;

package/dist/crypto.js

@@ -0,0 +1,64 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+export function hashApiKey(apiKey) {
+    return createHash('sha256').update(apiKey).digest('hex');
+}
+export function generateApiKey() {
+    return `spk_${randomBytes(24).toString('hex')}`;
+}
+export function apiKeyPrefix(apiKey) {
+    return apiKey.slice(0, 12);
+}
+export function createSessionToken(address, secret, ttlMs = 24 * 60 * 60 * 1000) {
+    const exp = Date.now() + ttlMs;
+    const payload = JSON.stringify({ address, exp });
+    const payloadB64 = Buffer.from(payload).toString('base64url');
+    const sig = createHmac('sha256', secret).update(payloadB64).digest('base64url');
+    return `${payloadB64}.${sig}`;
+}
+export function verifySessionToken(token, secret) {
+    const dot = token.indexOf('.');
+    if (dot === -1)
+        return null;
+    const payloadB64 = token.slice(0, dot);
+    const sig = token.slice(dot + 1);
+    const expected = createHmac('sha256', secret).update(payloadB64).digest('base64url');
+    try {
+        if (!timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString());
+        if (!payload.address || typeof payload.exp !== 'number')
+            return null;
+        if (Date.now() > payload.exp)
+            return null;
+        return { address: payload.address };
+    }
+    catch {
+        return null;
+    }
+}
+export function loadMasterSecret() {
+    const explicit = process.env.RELAY_MASTER_SECRET?.trim();
+    if (explicit)
+        return explicit;
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error('RELAY_MASTER_SECRET is required in production for per-wallet sponsor derivation');
+    }
+    const fallback = process.env.RELAY_SESSION_SECRET?.trim() ?? 'dev-master-secret-change-me';
+    console.warn('[relay] Warning: RELAY_MASTER_SECRET not set — using dev fallback (local only)');
+    return fallback;
+}
+export function loadSessionSecret() {
+    const secret = process.env.RELAY_SESSION_SECRET?.trim();
+    if (secret)
+        return secret;
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error('RELAY_SESSION_SECRET is required in production');
+    }
+    console.warn('[relay] Warning: RELAY_SESSION_SECRET not set — using dev fallback (local only)');
+    return 'dev-session-secret-change-me';
+}

package/dist/gas-tank.d.ts

@@ -0,0 +1,89 @@
+export interface WalletRecord {
+    id: string;
+    ownerAddress: string;
+    sponsorAddress: string;
+    totalSpentMicroStx: bigint;
+    reservedMicroStx: bigint;
+    txCount: number;
+    createdAt: string;
+}
+export interface ApiKeyRecord {
+    id: string;
+    walletId: string;
+    name: string;
+    keyHash: string;
+    keyPrefix: string;
+    revokedAt?: string;
+    createdAt: string;
+    /** Legacy v1 migration — plaintext lookup only */
+    legacyPlaintext?: string;
+}
+export interface SponsorLogRecord {
+    id: string;
+    walletId: string;
+    apiKeyId?: string;
+    txid: string;
+    feeMicroStx: bigint;
+    billingMode: 'gasless' | 'account-pay';
+    at: string;
+}
+export interface ResolvedApiKey {
+    wallet: WalletRecord;
+    apiKey: ApiKeyRecord;
+    sponsorPrivateKey: string;
+}
+/** @deprecated alias — GasTankStore is now wallet-scoped relay storage */
+export type ProjectRecord = WalletRecord & {
+    name?: string;
+    apiKey?: string;
+    gasTankAddress: string;
+    gasBalanceMicroStx: bigint;
+};
+/** Local dev: keep plaintext so wallet owners can reveal keys in admin UI. */
+export declare function devStoreApiKeys(): boolean;
+export declare class GasTankStore {
+    private readonly filePath;
+    private data;
+    private readonly masterSecret;
+    private readonly network;
+    constructor(filePath: string, masterSecret: string, network?: 'mainnet' | 'testnet');
+    private load;
+    private migrateFromV1;
+    private persist;
+    private toWallet;
+    private toApiKey;
+    ensureWallet(ownerAddress: string): WalletRecord;
+    getWalletByOwner(ownerAddress: string): WalletRecord | null;
+    /** @deprecated use getWalletById */
+    getById(id: string): WalletRecord | null;
+    getWalletById(id: string): WalletRecord | null;
+    listWallets(): WalletRecord[];
+    /** @deprecated use listWallets */
+    listProjects(): WalletRecord[];
+    listApiKeys(walletId: string): ApiKeyRecord[];
+    createApiKey(walletId: string, name: string): {
+        apiKey: string;
+        record: ApiKeyRecord;
+    };
+    canRevealApiKey(walletId: string, keyId: string): boolean;
+    revealApiKey(walletId: string, keyId: string): string;
+    revokeApiKey(walletId: string, keyId: string): ApiKeyRecord;
+    resolveApiKey(apiKey: string): ResolvedApiKey | null;
+    /** @deprecated use resolveApiKey */
+    getByApiKey(apiKey: string): ProjectRecord | null;
+    reserveGas(walletId: string, amountMicroStx: bigint): WalletRecord;
+    releaseReservation(walletId: string, amountMicroStx: bigint): WalletRecord;
+    recordSponsor(walletId: string, feeMicroStx: bigint, txid: string, billingMode: 'gasless' | 'account-pay', apiKeyId?: string, reservedMicroStx?: bigint): WalletRecord;
+    /** @deprecated virtual refill removed — deposit STX to sponsor address */
+    refill(_walletId: string, _amountMicroStx: bigint): WalletRecord;
+    /** @deprecated use ensureWallet + createApiKey */
+    createProject(name: string, _initialGasMicroStx?: bigint, _gasTankAddress?: string): ProjectRecord;
+    getLogs(walletId?: string): SponsorLogRecord[];
+    availableBalance(onChainMicroStx: bigint, wallet: WalletRecord): bigint;
+    getSponsorCredentials(walletId: string): {
+        wallet: WalletRecord;
+        sponsorPrivateKey: string;
+        sponsorAddress: string;
+    } | null;
+}
+export declare function defaultStorePath(): string;

package/dist/gas-tank.js

@@ -0,0 +1,286 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { apiKeyPrefix, generateApiKey, hashApiKey } from './crypto.js';
+import { deriveSponsorAddress, deriveSponsorPrivateKey } from './sponsor-derivation.js';
+/** Local dev: keep plaintext so wallet owners can reveal keys in admin UI. */
+export function devStoreApiKeys() {
+    const flag = process.env.RELAY_DEV_STORE_API_KEYS?.trim().toLowerCase();
+    if (flag === 'true' || flag === '1')
+        return true;
+    if (flag === 'false' || flag === '0')
+        return false;
+    return process.env.NODE_ENV !== 'production';
+}
+export class GasTankStore {
+    filePath;
+    data;
+    masterSecret;
+    network;
+    constructor(filePath, masterSecret, network = 'testnet') {
+        this.filePath = filePath;
+        this.masterSecret = masterSecret;
+        this.network = network;
+        mkdirSync(dirname(filePath), { recursive: true });
+        this.data = this.load();
+    }
+    load() {
+        if (!existsSync(this.filePath)) {
+            return { version: 2, wallets: [], apiKeys: [], logs: [] };
+        }
+        const raw = JSON.parse(readFileSync(this.filePath, 'utf8'));
+        if (raw.version === 2)
+            return raw;
+        return this.migrateFromV1(raw);
+    }
+    migrateFromV1(legacy) {
+        const data = { version: 2, wallets: [], apiKeys: [], logs: [] };
+        for (const project of legacy.projects ?? []) {
+            const ownerAddress = `legacy:${project.id}`;
+            const sponsorAddress = project.gasTankAddress ||
+                deriveSponsorAddress(this.masterSecret, ownerAddress, this.network);
+            const walletId = project.id;
+            data.wallets.push({
+                id: walletId,
+                ownerAddress,
+                sponsorAddress,
+                totalSpentMicroStx: project.totalSpentMicroStx ?? '0',
+                reservedMicroStx: '0',
+                txCount: project.txCount ?? 0,
+                createdAt: project.createdAt ?? new Date().toISOString(),
+            });
+            data.apiKeys.push({
+                id: randomBytes(6).toString('hex'),
+                walletId,
+                name: project.name ?? 'Legacy project',
+                keyHash: hashApiKey(project.apiKey),
+                keyPrefix: apiKeyPrefix(project.apiKey),
+                createdAt: project.createdAt ?? new Date().toISOString(),
+                legacyPlaintext: project.apiKey,
+            });
+        }
+        for (const log of legacy.logs ?? []) {
+            data.logs.push({
+                id: log.id,
+                walletId: log.projectId,
+                apiKeyId: undefined,
+                txid: log.txid,
+                feeMicroStx: log.feeMicroStx,
+                billingMode: log.billingMode,
+                at: log.at,
+            });
+        }
+        this.data = data;
+        this.persist();
+        console.log(`[relay] Migrated ${data.wallets.length} legacy project(s) to wallet model`);
+        return data;
+    }
+    persist() {
+        writeFileSync(this.filePath, JSON.stringify(this.data, null, 2));
+    }
+    toWallet(row) {
+        return {
+            ...row,
+            totalSpentMicroStx: BigInt(row.totalSpentMicroStx),
+            reservedMicroStx: BigInt(row.reservedMicroStx),
+        };
+    }
+    toApiKey(row) {
+        return { ...row };
+    }
+    ensureWallet(ownerAddress) {
+        const existing = this.data.wallets.find((w) => w.ownerAddress.toLowerCase() === ownerAddress.toLowerCase());
+        if (existing)
+            return this.toWallet(existing);
+        const sponsorAddress = deriveSponsorAddress(this.masterSecret, ownerAddress, this.network);
+        const wallet = {
+            id: randomBytes(8).toString('hex'),
+            ownerAddress,
+            sponsorAddress,
+            totalSpentMicroStx: '0',
+            reservedMicroStx: '0',
+            txCount: 0,
+            createdAt: new Date().toISOString(),
+        };
+        this.data.wallets.push(wallet);
+        this.persist();
+        return this.toWallet(wallet);
+    }
+    getWalletByOwner(ownerAddress) {
+        const row = this.data.wallets.find((w) => w.ownerAddress.toLowerCase() === ownerAddress.toLowerCase());
+        return row ? this.toWallet(row) : null;
+    }
+    /** @deprecated use getWalletById */
+    getById(id) {
+        return this.getWalletById(id);
+    }
+    getWalletById(id) {
+        const row = this.data.wallets.find((w) => w.id === id);
+        return row ? this.toWallet(row) : null;
+    }
+    listWallets() {
+        return this.data.wallets.map((w) => this.toWallet(w));
+    }
+    /** @deprecated use listWallets */
+    listProjects() {
+        return this.listWallets();
+    }
+    listApiKeys(walletId) {
+        return this.data.apiKeys
+            .filter((k) => k.walletId === walletId && !k.revokedAt)
+            .map((k) => this.toApiKey(k));
+    }
+    createApiKey(walletId, name) {
+        const wallet = this.getWalletById(walletId);
+        if (!wallet)
+            throw new Error('Wallet not found');
+        const apiKey = generateApiKey();
+        const record = {
+            id: randomBytes(6).toString('hex'),
+            walletId,
+            name,
+            keyHash: hashApiKey(apiKey),
+            keyPrefix: apiKeyPrefix(apiKey),
+            createdAt: new Date().toISOString(),
+            ...(devStoreApiKeys() ? { legacyPlaintext: apiKey } : {}),
+        };
+        this.data.apiKeys.push(record);
+        this.persist();
+        return { apiKey, record: this.toApiKey(record) };
+    }
+    canRevealApiKey(walletId, keyId) {
+        const row = this.data.apiKeys.find((k) => k.id === keyId && k.walletId === walletId && !k.revokedAt);
+        return Boolean(row?.legacyPlaintext);
+    }
+    revealApiKey(walletId, keyId) {
+        const row = this.data.apiKeys.find((k) => k.id === keyId && k.walletId === walletId && !k.revokedAt);
+        if (!row?.legacyPlaintext) {
+            throw new Error('API key not retrievable — create a new key or use a copy saved at creation time');
+        }
+        return row.legacyPlaintext;
+    }
+    revokeApiKey(walletId, keyId) {
+        const row = this.data.apiKeys.find((k) => k.id === keyId && k.walletId === walletId);
+        if (!row)
+            throw new Error('API key not found');
+        if (row.revokedAt)
+            throw new Error('API key already revoked');
+        row.revokedAt = new Date().toISOString();
+        this.persist();
+        return this.toApiKey(row);
+    }
+    resolveApiKey(apiKey) {
+        const hash = hashApiKey(apiKey);
+        const row = this.data.apiKeys.find((k) => k.keyHash === hash && !k.revokedAt) ??
+            this.data.apiKeys.find((k) => k.legacyPlaintext === apiKey && !k.revokedAt);
+        if (!row)
+            return null;
+        const walletRow = this.data.wallets.find((w) => w.id === row.walletId);
+        if (!walletRow)
+            return null;
+        const wallet = this.toWallet(walletRow);
+        return {
+            wallet,
+            apiKey: this.toApiKey(row),
+            sponsorPrivateKey: deriveSponsorPrivateKey(this.masterSecret, wallet.ownerAddress),
+        };
+    }
+    /** @deprecated use resolveApiKey */
+    getByApiKey(apiKey) {
+        const resolved = this.resolveApiKey(apiKey);
+        if (!resolved)
+            return null;
+        return {
+            ...resolved.wallet,
+            id: resolved.wallet.id,
+            name: resolved.apiKey.name,
+            apiKey,
+            gasTankAddress: resolved.wallet.sponsorAddress,
+            gasBalanceMicroStx: 0n,
+        };
+    }
+    reserveGas(walletId, amountMicroStx) {
+        const row = this.data.wallets.find((w) => w.id === walletId);
+        if (!row)
+            throw new Error('Wallet not found');
+        row.reservedMicroStx = (BigInt(row.reservedMicroStx) + amountMicroStx).toString();
+        this.persist();
+        return this.toWallet(row);
+    }
+    releaseReservation(walletId, amountMicroStx) {
+        const row = this.data.wallets.find((w) => w.id === walletId);
+        if (!row)
+            throw new Error('Wallet not found');
+        const next = BigInt(row.reservedMicroStx) - amountMicroStx;
+        row.reservedMicroStx = (next > 0n ? next : 0n).toString();
+        this.persist();
+        return this.toWallet(row);
+    }
+    recordSponsor(walletId, feeMicroStx, txid, billingMode, apiKeyId, reservedMicroStx) {
+        const row = this.data.wallets.find((w) => w.id === walletId);
+        if (!row)
+            throw new Error('Wallet not found');
+        if (reservedMicroStx && reservedMicroStx > 0n) {
+            const next = BigInt(row.reservedMicroStx) - reservedMicroStx;
+            row.reservedMicroStx = (next > 0n ? next : 0n).toString();
+        }
+        if (billingMode === 'gasless') {
+            row.totalSpentMicroStx = (BigInt(row.totalSpentMicroStx) + feeMicroStx).toString();
+        }
+        row.txCount += 1;
+        this.data.logs.unshift({
+            id: randomBytes(6).toString('hex'),
+            walletId,
+            apiKeyId,
+            txid,
+            feeMicroStx: feeMicroStx.toString(),
+            billingMode,
+            at: new Date().toISOString(),
+        });
+        this.data.logs = this.data.logs.slice(0, 500);
+        this.persist();
+        return this.toWallet(row);
+    }
+    /** @deprecated virtual refill removed — deposit STX to sponsor address */
+    refill(_walletId, _amountMicroStx) {
+        throw new Error('Virtual refill is disabled. Deposit STX to your sponsor gas tank address on-chain.');
+    }
+    /** @deprecated use ensureWallet + createApiKey */
+    createProject(name, _initialGasMicroStx = 0n, _gasTankAddress = '') {
+        const ownerAddress = `legacy:${randomBytes(8).toString('hex')}`;
+        const wallet = this.ensureWallet(ownerAddress);
+        const { apiKey } = this.createApiKey(wallet.id, name);
+        return {
+            ...wallet,
+            name,
+            apiKey,
+            gasTankAddress: wallet.sponsorAddress,
+            gasBalanceMicroStx: 0n,
+        };
+    }
+    getLogs(walletId) {
+        return this.data.logs
+            .filter((l) => !walletId || l.walletId === walletId)
+            .map((l) => ({
+            ...l,
+            feeMicroStx: BigInt(l.feeMicroStx),
+        }));
+    }
+    availableBalance(onChainMicroStx, wallet) {
+        const available = onChainMicroStx - wallet.reservedMicroStx;
+        return available > 0n ? available : 0n;
+    }
+    getSponsorCredentials(walletId) {
+        const wallet = this.getWalletById(walletId);
+        if (!wallet)
+            return null;
+        return {
+            wallet,
+            sponsorPrivateKey: deriveSponsorPrivateKey(this.masterSecret, wallet.ownerAddress),
+            sponsorAddress: wallet.sponsorAddress,
+        };
+    }
+}
+export function defaultStorePath() {
+    return join(process.cwd(), 'data', 'gas-tank.json');
+}

package/dist/gas-tank.test.d.ts

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

package/dist/gas-tank.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { GasTankStore } from './gas-tank.js';
+import { deriveSponsorAddress } from './sponsor-derivation.js';
+import { hashApiKey } from './crypto.js';
+const MASTER = 'test-master-secret';
+const OWNER = 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM';
+describe('GasTankStore', () => {
+    let dir;
+    let store;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'gas-tank-'));
+        store = new GasTankStore(join(dir, 'tank.json'), MASTER, 'testnet');
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it('creates wallet with derived sponsor address', () => {
+        const wallet = store.ensureWallet(OWNER);
+        expect(wallet.ownerAddress).toBe(OWNER);
+        expect(wallet.sponsorAddress).toBe(deriveSponsorAddress(MASTER, OWNER, 'testnet'));
+    });
+    it('creates hashed API keys under unified wallet tank', () => {
+        const wallet = store.ensureWallet(OWNER);
+        const { apiKey, record } = store.createApiKey(wallet.id, 'Demo app');
+        expect(apiKey.startsWith('spk_')).toBe(true);
+        expect(record.keyHash).toBe(hashApiKey(apiKey));
+        expect(record.keyPrefix).toBe(apiKey.slice(0, 12));
+        const resolved = store.resolveApiKey(apiKey);
+        expect(resolved?.wallet.id).toBe(wallet.id);
+        expect(resolved?.sponsorPrivateKey.endsWith('01')).toBe(true);
+    });
+    it('reveals API keys in non-production dev mode', () => {
+        const wallet = store.ensureWallet(OWNER);
+        const { apiKey, record } = store.createApiKey(wallet.id, 'Reveal me');
+        expect(store.canRevealApiKey(wallet.id, record.id)).toBe(true);
+        expect(store.revealApiKey(wallet.id, record.id)).toBe(apiKey);
+    });
+    it('revokes API keys', () => {
+        const wallet = store.ensureWallet(OWNER);
+        const { apiKey, record } = store.createApiKey(wallet.id, 'Temp');
+        expect(store.resolveApiKey(apiKey)).not.toBeNull();
+        store.revokeApiKey(wallet.id, record.id);
+        expect(store.resolveApiKey(apiKey)).toBeNull();
+    });
+    it('tracks reservations and sponsor records', () => {
+        const wallet = store.ensureWallet(OWNER);
+        store.reserveGas(wallet.id, 50000n);
+        const updated = store.recordSponsor(wallet.id, 50000n, 'abc123', 'gasless', undefined, 50000n);
+        expect(updated.totalSpentMicroStx).toBe(50000n);
+        expect(updated.reservedMicroStx).toBe(0n);
+        expect(updated.txCount).toBe(1);
+    });
+    it('rejects virtual refill', () => {
+        const wallet = store.ensureWallet(OWNER);
+        expect(() => store.refill(wallet.id, 100n)).toThrow(/Deposit STX/);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createRelayApp } from './app.js';
+export { SponsorService } from './sponsor.js';
+export { AccountService } from './account-service.js';
+export { RateLimiter, isContractAllowed } from './rate-limit.js';
+export type { RelayConfig, RelayPolicy, SponsorRequest, SponsorResult } from './types.js';
+export type { EnsureAccountResult } from './account-service.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createRelayApp } from './app.js';
+export { SponsorService } from './sponsor.js';
+export { AccountService } from './account-service.js';
+export { RateLimiter, isContractAllowed } from './rate-limit.js';

package/dist/load-env.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Load packages/relay/.env if present. Never commit that file.
+ */
+export declare function loadRelayEnv(): void;