prividium 0.17.0 → 0.18.0

package/README.md

@@ -404,7 +404,7 @@ interface PrividiumSiweConfig {
   chain: Chain; // Viem chain configuration (without rpcUrls)
   prividiumApiBaseUrl: string; // Permissions API service base URL
   account: LocalAccount; // Viem account for signing (e.g. from privateKeyToAccount)
-  domain: string; // Domain for SIWE message
+  domain?: string; // Optional: domain for SIWE message (defaults to server-configured domain)
   storage?: Storage; // Custom storage (defaults to MemoryStorage)
   autoReauthenticate?: boolean; // Auto-reauth on session expiry (default: true)
   onAuthExpiry?: () => void; // Called when auth expires and reauth is disabled/failed
@@ -542,27 +542,43 @@ to use your existing deployment workflows.
 
 ### Core Command
 
+Browser login mode (interactive):
+
 ```bash
 prividium proxy \
-  --rpc-url https://<your-prividium-rpc> \
   --user-panel-url https://<your-user-panel> \
   [--port 24101] [--host 127.0.0.1] [--config-path <path>]
 ```
 
-What happens:
+Private key mode (non-interactive):
+
+```bash
+prividium proxy \
+  --api-url https://<your-prividium-api> \
+  --private-key 0x<your-private-key>
+```
+
+What happens (browser login mode):
 
-- Validates that `--user-panel-url` points to a Prividium™ User Panel before starting. Exits with an error if an Admin
-  Panel URL is detected; warns and continues if the URL cannot be reached or confirmed.
+- Discovers the API URL automatically from the User Panel's `prividium-api-url` meta tag.
 - Prints a local URL to open in your browser for sign-in.
-- After successful sign-in, the proxy is available at `http://127.0.0.1:24101/rpc`.
-- All requests are forwarded to your `--rpc-url` with `Authorization: Bearer <token>`.
+- After successful sign-in, the proxy is available at `http://127.0.0.1:24101`.
+- All requests are forwarded to the API with `Authorization: Bearer <token>`.
 - Requests are rejected until authentication completes.
 
+What happens (private key mode):
+
+- Authenticates immediately using SIWE with the provided private key (no browser required).
+- Re-authenticates automatically when the session expires.
+- Proxy is available at `http://127.0.0.1:24101` once authenticated.
+
 Flags:
 
-- `--rpc-url, -r` (string): Target Prividium™ RPC URL.
-- `--user-panel-url, -u` (string): URL of the Prividium™ User Panel used for sign-in. The command validates this URL on
-  startup and exits with an error if it detects an Admin Panel URL.
+- `--api-url, --rpc-url, -r` (string): Target Prividium™ API URL. Required with `--private-key`.
+- `--user-panel-url, -u` (string): URL of the Prividium™ User Panel for browser-based login. The API URL is discovered
+  automatically from the User Panel when `--api-url` is not provided.
+- `--private-key` (string): Ethereum private key for SIWE authentication (skips browser login). Can also be set via
+  `PRIVIDIUM_PRIVATE_KEY`.
 - `--port, -p` (number, default `24101`): Local proxy port. This has to match with the port configured in the admin
   panel, which by default uses this same port.
 - `--host, -h` (string, default `127.0.0.1`): host binded to server. By default only connections comming from local
@@ -572,7 +588,8 @@ Flags:
 
 Environment variables (optional):
 
-- `PRIVIDIUM_RPC_URL`
+- `PRIVIDIUM_API_URL` (or `PRIVIDIUM_RPC_URL`)
+- `PRIVIDIUM_PRIVATE_KEY`
 - `USER_PANEL_URL`
 
 Precedence: CLI flags > environment variables > saved config file.
@@ -582,19 +599,15 @@ Precedence: CLI flags > environment variables > saved config file.
 When running the full Prividium stack locally (`pnpm dev`), use:
 
 ```bash
-npx prividium proxy \
-  --rpc-url http://localhost:8000 \
-  --user-panel-url http://localhost:3001
+npx prividium proxy --user-panel-url http://localhost:3001
 ```
 
-Point Foundry, Hardhat, or your scripts at `http://127.0.0.1:24101/rpc` after sign-in.
+Point Foundry, Hardhat, or your scripts at `http://127.0.0.1:24101` after sign-in.
 
 ### Config Commands
 
 ```bash
-prividium config set \
-  --rpc-url https://<your-prividium-rpc> \
-  --user-panel-url https://<your-user-panel>
+prividium config set --api-url https://<your-prividium-api>
 
 prividium config print     # Show current values
 prividium config path      # Show config file location

package/bin/cli.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import '../dist/cli/index.js';
+import '../dist/cli/cli/index.js';

package/dist/cli/{commands → cli/commands}/config.js

@@ -20,21 +20,13 @@ export const addConfig = (cli) => {
         .command('clear', 'Clears current configuration file', (yargs) => yargs, (args) => clearConfig(args.configPath))
         .command('path', 'Shows local config file path', (yargs) => yargs, (args) => configPath(args.configPath))
         .command('print', 'Prints current configuration', (yargs) => yargs, (args) => printConfig(args.configPath))
-        .command('set', 'Updates config', (yargs) => yargs
-        .option('rpcUrl', {
-        alias: ['rpc-url', 'r'],
-        description: 'Specifies target Prividium™ rpc url. These takes precedence over config file and env variable.',
+        .command('set', 'Updates config', (yargs) => yargs.option('apiUrl', {
+        alias: ['api-url', 'rpc-url', 'r'],
+        description: 'Specifies target Prividium™ API url.',
         demandOption: true,
         type: 'string'
-    })
-        .option('userPanelUrl', {
-        alias: ['user-panel-url', 'u'],
-        description: 'Specifies url used to log in into the Prividium™ network. Takes precedence over config file and env variable',
-        type: 'string',
-        demandOption: true
     }), (args) => updateConfig({
-        prividiumRpcUrl: args.rpcUrl,
-        userPanelUrl: args.userPanelUrl
+        apiUrl: args.apiUrl
     }, args.configPath))
         .demandCommand());
 };

package/dist/cli/cli/commands/proxy.js

@@ -0,0 +1,255 @@
+import { intro, log, text } from '@clack/prompts';
+import color from 'kleur';
+import { privateKeyToAccount } from 'viem/accounts';
+import { z } from 'zod';
+import { MemoryStorage } from '../../src/memory-storage.js';
+import { SiweAuth } from '../../src/siwe-auth.js';
+import { TokenManager } from '../../src/storage.js';
+import { CreationWorkflow } from '../server/connection-workflow.js';
+import { buildServer } from '../server/server.js';
+import { showPrividiumHeader } from './utils/show-prividium-header.js';
+import { gatherApiUrl } from './utils/url-config.js';
+const DEFAULT_PORT = 24101;
+const PRIVATE_KEY_REGEX = /^0x[0-9a-fA-F]{64}$/;
+function checkHostAndPortWarnings(host, port, allowExternalAccess) {
+    if (port !== DEFAULT_PORT) {
+        log.warn(`Non standard port detected: ${port}. Redirect from prividium auth might not work.`);
+    }
+    if (host !== '127.0.0.1' && host !== 'localhost') {
+        if (!allowExternalAccess) {
+            log.error(`${color.bold('ERROR')}: In order to use a host different than local host you need to set --unsecureAllowOutsideAccess flag.`);
+            process.exit(1);
+        }
+        if (host === '0.0.0.0') {
+            log.warn(`${color.bold('WARNING')}: Your local proxy will be exposed outside your current device.`);
+        }
+        else {
+            log.warn(`${color.bold('WARNING')}: Non standard host: ${host}. Your proxy might be open for other devices. Redirect from prividium auth might not work.`);
+        }
+    }
+}
+const wellKnownMetadataSchema = z.object({
+    apiUrl: z.string().optional()
+});
+// Fetches /.well-known/prividium from the User Panel and returns its apiUrl.
+async function discoverApiUrlFromUserPanel(userPanelUrl) {
+    const wellKnownUrl = new URL('/.well-known/prividium', userPanelUrl).toString();
+    let response;
+    try {
+        response = await fetch(wellKnownUrl, { signal: AbortSignal.timeout(5000) });
+    }
+    catch (error) {
+        throw new Error(`Could not reach User Panel at ${userPanelUrl}.\n` +
+            `  ${error instanceof Error ? error.message : String(error)}\n` +
+            '  Please verify the URL is correct and the User Panel is running.');
+    }
+    if (!response.ok) {
+        throw new Error(`User Panel at ${userPanelUrl} did not return /.well-known/prividium (HTTP ${response.status}).\n` +
+            '  Please verify the URL points to a Prividium™ User Panel, or pass --api-url directly.');
+    }
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch {
+        throw new Error(`User Panel at ${userPanelUrl} returned non-JSON for /.well-known/prividium.\n` +
+            '  Please verify the URL points to a Prividium™ User Panel, or pass --api-url directly.');
+    }
+    const parsed = wellKnownMetadataSchema.safeParse(json);
+    if (!parsed.success || !parsed.data.apiUrl) {
+        throw new Error(`User Panel at ${userPanelUrl} did not advertise an apiUrl in /.well-known/prividium.\n` +
+            '  Please pass --api-url directly.');
+    }
+    return parsed.data.apiUrl;
+}
+async function resolveUserPanelUrl(opts) {
+    const explicit = opts.userPanelUrl ?? process.env.USER_PANEL_URL;
+    if (explicit) {
+        const res = z.url().safeParse(explicit);
+        if (!res.success) {
+            throw new Error(`Invalid user panel url provided: ${explicit}`);
+        }
+        log.info(`Using user panel url: ${explicit}`);
+        return explicit;
+    }
+    const prompted = await text({
+        message: 'Please insert your Prividium™ User Panel url',
+        validate(value) {
+            const parsed = z.url().safeParse(value);
+            if (!parsed.success) {
+                return 'Please provide a valid url';
+            }
+        }
+    });
+    if (typeof prompted === 'symbol') {
+        throw new Error('Canceled by the user');
+    }
+    return prompted;
+}
+async function startServerWithPrivateKey(opts) {
+    const privateKey = opts.privateKey;
+    if (!PRIVATE_KEY_REGEX.test(privateKey)) {
+        log.error('Invalid private key format. Expected 0x-prefixed 32-byte hex string.');
+        process.exit(1);
+    }
+    const account = privateKeyToAccount(privateKey);
+    showPrividiumHeader();
+    intro('Starting Prividium™ proxy (private key auth)');
+    const apiUrl = await gatherApiUrl({
+        configPath: opts.configPath,
+        apiUrl: opts.apiUrl,
+        logProvidedUrls: true
+    });
+    checkHostAndPortWarnings(opts.host, opts.port, opts.allowExternalAccess);
+    const storage = new MemoryStorage();
+    const tokenManager = new TokenManager(storage, 0, apiUrl);
+    const siweAuth = new SiweAuth({
+        account,
+        prividiumApiBaseUrl: apiUrl,
+        tokenManager
+    });
+    log.info(`Authenticating as ${account.address}...`);
+    const tokenData = await siweAuth.authorize();
+    log.info('Authentication successful');
+    const app = buildServer({
+        apiUrl,
+        host: opts.host,
+        port: opts.port,
+        initialToken: {
+            accessToken: tokenData.rawToken,
+            expiresAt: tokenData.expiresAt
+        },
+        async onReAuth() {
+            log.info('Session expired, re-authenticating...');
+            const newToken = await siweAuth.authorize();
+            log.info('Re-authentication successful');
+            return { accessToken: newToken.rawToken, expiresAt: newToken.expiresAt };
+        },
+        async onSubmit() { },
+        onCall(methodName) {
+            log.message(methodName);
+        },
+        onReAuthNeeded() { },
+        onError(err) {
+            log.error(`Error: ${err.message}`);
+        }
+    });
+    await app.listen({
+        port: opts.port,
+        host: opts.host
+    });
+    const serverUrl = `http://${opts.host}:${opts.port}`;
+    log.info(`Your proxy rpc is ready: \n\n${color.bold(serverUrl)}\n`);
+    log.info('Waiting for logs...');
+}
+async function startServer(opts) {
+    const workflow = new CreationWorkflow(opts.host, opts.port);
+    workflow.start();
+    const userPanelUrl = await resolveUserPanelUrl(opts);
+    let apiUrl;
+    if (opts.apiUrl) {
+        apiUrl = opts.apiUrl;
+        log.info(`Using Prividium™ API url: ${apiUrl}`);
+    }
+    else {
+        log.info('Discovering API URL from User Panel...');
+        apiUrl = await discoverApiUrlFromUserPanel(userPanelUrl);
+        log.info(`Using Prividium™ API url: ${apiUrl}`);
+    }
+    checkHostAndPortWarnings(opts.host, opts.port, opts.allowExternalAccess);
+    const serverUrl = `http://${opts.host}:${opts.port}`;
+    const app = buildServer({
+        apiUrl,
+        userPanelUrl,
+        host: opts.host,
+        port: opts.port,
+        async onSubmit() {
+            await workflow.onSubmit();
+        },
+        onCall(methodName) {
+            workflow.onMessage(methodName);
+        },
+        onReAuthNeeded() {
+            workflow.onMessage(`Please login again: ${serverUrl}`);
+        },
+        onError: (err) => {
+            workflow.onError(err);
+        }
+    });
+    await app.listen({
+        port: opts.port,
+        host: opts.host
+    });
+    await workflow.waitForAuthentication(serverUrl);
+}
+export const addProxy = (cli) => {
+    return cli.command('proxy', 'Starts authenticated rpc proxy server', (yargs) => yargs
+        .option('apiUrl', {
+        alias: ['api-url', 'rpc-url', 'r'],
+        description: 'Specifies target Prividium™ API url. Required with --private-key.',
+        demandOption: false,
+        type: 'string'
+    })
+        .option('userPanelUrl', {
+        alias: ['user-panel-url', 'u'],
+        description: 'Specifies the User Panel url for browser-based login. If --api-url is omitted, it is fetched from the User Panel via /.well-known/prividium.',
+        type: 'string'
+    })
+        .option('configPath', {
+        alias: ['c', 'config-path', 'config'],
+        description: 'Path for config file. By default config file is stored under user personal folder',
+        type: 'string',
+        demandOption: false
+    })
+        .option('port', {
+        alias: ['p'],
+        description: 'Port used for local proxy. This has to match with the port configured in your Prividium™ network.',
+        default: DEFAULT_PORT,
+        type: 'number'
+    })
+        .option('host', {
+        alias: 'h',
+        description: 'Host used for local server. By default traffic from outside localhost is disabled.',
+        default: '127.0.0.1',
+        type: 'string'
+    })
+        .option('unsecureAllowOutsideAccess', {
+        alias: ['unsecure-allow-outside-access'],
+        description: 'Allow server to be exposed to the network (accessible by other devices)',
+        default: false,
+        type: 'boolean'
+    })
+        .option('privateKey', {
+        alias: ['private-key'],
+        description: 'Ethereum private key for SIWE authentication (skips browser login). Can also be set via PRIVIDIUM_PRIVATE_KEY env var.',
+        type: 'string'
+    }), async (args) => {
+        try {
+            const privateKey = args.privateKey ?? process.env.PRIVIDIUM_PRIVATE_KEY;
+            const rpcUrlEnv = process.env.PRIVIDIUM_RPC_URL;
+            const apiUrl = args.apiUrl ??
+                process.env.PRIVIDIUM_API_URL ??
+                (rpcUrlEnv ? rpcUrlEnv.replace(/\/rpc\/?$/, '') : undefined);
+            const opts = {
+                apiUrl,
+                userPanelUrl: args.userPanelUrl,
+                privateKey,
+                configPath: args.configPath,
+                port: args.port,
+                host: args.host,
+                allowExternalAccess: args.unsecureAllowOutsideAccess
+            };
+            if (privateKey) {
+                await startServerWithPrivateKey(opts);
+            }
+            else {
+                await startServer(opts);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Prividium proxy failed: ${message}`);
+            process.exit(1);
+        }
+    });
+};

package/dist/cli/{commands → cli/commands}/utils/url-config.js

@@ -2,6 +2,7 @@ import { confirm, log, text } from '@clack/prompts';
 import { z } from 'zod';
 import { ConfigFile } from '../../server/config-file.js';
 const envSchema = z.object({
+    PRIVIDIUM_API_URL: z.string().optional(),
     PRIVIDIUM_RPC_URL: z.string().optional(),
     USER_PANEL_URL: z.string().optional()
 });
@@ -30,12 +31,28 @@ async function askForUrl(maybeUrl, name, logProvidedUrls) {
     }
     return { url, prompted: true };
 }
+export async function gatherApiUrl({ configPath, apiUrl, logProvidedUrls = false }) {
+    const config = new ConfigFile(configPath);
+    const configData = config.read();
+    const env = envSchema.parse(process.env);
+    const givenApiUrl = apiUrl ?? env.PRIVIDIUM_API_URL ?? configData.apiUrl;
+    const { url: resolvedApiUrl, prompted } = await askForUrl(givenApiUrl, 'Prividium™ API', logProvidedUrls);
+    if (prompted) {
+        const confirmation = await confirm({
+            message: 'Do you want to store this config for future usages?'
+        });
+        if (confirmation) {
+            config.write({ apiUrl: resolvedApiUrl });
+        }
+    }
+    return resolvedApiUrl;
+}
 export async function gatherUrlConfig({ configPath, rpcUrl, userPanelUrl, rpcUrlLabel, logProvidedUrls = false }) {
     const config = new ConfigFile(configPath);
     const configData = config.read();
     const env = envSchema.parse(process.env);
-    const givenRpcUrl = rpcUrl ?? env.PRIVIDIUM_RPC_URL ?? configData.prividiumRpcUrl;
-    const givenUserPanelUrl = userPanelUrl ?? env.USER_PANEL_URL ?? configData.userPanelUrl;
+    const givenRpcUrl = rpcUrl ?? env.PRIVIDIUM_API_URL ?? env.PRIVIDIUM_RPC_URL ?? configData.apiUrl;
+    const givenUserPanelUrl = userPanelUrl ?? env.USER_PANEL_URL;
     const { url: prividiumRpcUrl, prompted: promptedRpc } = await askForUrl(givenRpcUrl, rpcUrlLabel, logProvidedUrls);
     const { url: resolvedUserPanelUrl, prompted: promptedPanel } = await askForUrl(givenUserPanelUrl, 'user panel', logProvidedUrls);
     if (promptedRpc || promptedPanel) {
@@ -43,7 +60,7 @@ export async function gatherUrlConfig({ configPath, rpcUrl, userPanelUrl, rpcUrl
             message: 'Do you want to store this config for future usages?'
         });
         if (confirmation) {
-            config.write({ prividiumRpcUrl, userPanelUrl: resolvedUserPanelUrl });
+            config.write({ apiUrl: prividiumRpcUrl });
         }
     }
     return { prividiumRpcUrl, userPanelUrl: resolvedUserPanelUrl };

package/dist/cli/{server → cli/server}/config-file.js

@@ -7,10 +7,30 @@ import { z } from 'zod';
 // biome-ignore lint/suspicious/noExplicitAny: CJS/ESM interop
 const appDirsFn = appDirs.default;
 const dirs = appDirsFn({ appName: 'prividium-proxy' });
-const urlConfigSchema = z.object({
-    prividiumRpcUrl: z.string(),
-    userPanelUrl: z.string()
-});
+// Source of truth for the on-disk config-file shapes the SDK accepts.
+// `latest` is what `write()` produces today.
+// Any other entry is keyed by the last SDK version that wrote that shape;
+// it exists only so older config files keep working after a user upgrades.
+// To add a new legacy entry: copy the previous `latest` into a new `vX_Y`
+// key, then change `latest` to the new shape and add a branch in `migrate()`.
+const schemas = {
+    latest: z.object({
+        apiUrl: z.string()
+    }),
+    v0_17: z.object({
+        prividiumRpcUrl: z.string(),
+        userPanelUrl: z.string()
+    })
+};
+function migrate(json) {
+    const latest = schemas.latest.safeParse(json);
+    if (latest.success)
+        return latest.data;
+    const v0_17 = schemas.v0_17.safeParse(json);
+    if (v0_17.success)
+        return { apiUrl: v0_17.data.prividiumRpcUrl };
+    return null;
+}
 export class ConfigFile {
     filePath;
     constructor(filePath) {
@@ -28,7 +48,8 @@ export class ConfigFile {
         else {
             const data = readFileSync(this.filePath).toString();
             try {
-                return urlConfigSchema.parse(JSON.parse(data));
+                const json = JSON.parse(data);
+                return migrate(json) ?? {};
             }
             catch {
                 rmSync(this.filePath);
@@ -48,9 +69,8 @@ export class ConfigFile {
         }
     }
     print() {
-        const { prividiumRpcUrl, userPanelUrl } = this.read();
-        console.log(`${color.bold('Prividium™ rpc url')}: ${prividiumRpcUrl}`);
-        console.log(`${color.bold('Log in url')}: ${userPanelUrl}`);
+        const { apiUrl } = this.read();
+        console.log(`${color.bold('Prividium™ API url')}: ${apiUrl}`);
     }
     printPath() {
         console.log(this.filePath);

package/dist/cli/{server → cli/server}/connection-workflow.js

@@ -48,7 +48,7 @@ export class CreationWorkflow {
             this.submitCallback('Authentication successful!');
             await setTimeout(100);
         }
-        log.info(`Your proxy rpc is ready! 🚀: \n\n${color.bold(`http://${this.host}:${this.port}/rpc`)}\n`);
+        log.info(`Your proxy rpc is ready! 🚀: \n\n${color.bold(`http://${this.host}:${this.port}`)}\n`);
         log.info('Waiting for logs...');
     }
     onMessage(msg) {

package/dist/cli/{server → cli/server}/server.js

@@ -29,8 +29,9 @@ export function buildServer(config) {
         return reply.status(500).send({ error: err.message });
     });
     const state = randomStateString();
-    let accessToken = '';
-    let expiresAt = new Date();
+    let accessToken = config.initialToken?.accessToken ?? '';
+    let expiresAt = config.initialToken?.expiresAt ?? new Date();
+    let reauthPromise = null;
     app.register(fastifyStatic, { root: path.join(import.meta.dirname, '..', 'static') });
     app.get('/health', async (_req, reply) => {
         return reply.send('ok');
@@ -40,7 +41,7 @@ export function buildServer(config) {
         return reply.sendFile(path.join('start.html'));
     });
     app.get('/redirect-uri', async (_req, reply) => {
-        const url = new URL('/auth/authorize', config.userPanelUrl);
+        const url = new URL('/auth/authorize', config.userPanelUrl ?? config.apiUrl);
         url.searchParams.set('client_id', 'proxy-cli');
         url.searchParams.set('redirect_uri', `http://localhost:24101/callback`);
         url.searchParams.set('state', state);
@@ -62,7 +63,7 @@ export function buildServer(config) {
         if (req.body.state !== state) {
             throw new Error('invalid state received');
         }
-        const { expiresAt: expirationMoment } = await fetch(config.prividiumRpcUrl.replace('rpc', 'api/auth/current-session'), {
+        const { expiresAt: expirationMoment } = await fetch(new URL('/api/auth/current-session', config.apiUrl), {
             method: 'GET',
             headers: { authorization: `Bearer ${req.body.token}` }
         }).then((res) => {
@@ -82,18 +83,35 @@ export function buildServer(config) {
         await config.onSubmit();
         return reply.send('ok');
     });
-    app.register(fastifyHttpProxy, {
-        upstream: config.prividiumRpcUrl,
-        prefix: '/rpc',
+    const proxyOptions = (prefix) => ({
+        upstream: config.apiUrl,
+        prefix,
         rewritePrefix: '/rpc',
         httpMethods: ['POST'],
-        routes: ['/'],
-        preValidation: (request, _reply, done) => {
+        preValidation: async (request) => {
             const method = rpcReqSchema.safeParse(request.body);
             if (new Date() > expiresAt) {
-                config.onReAuthNeeded();
-                done(new Error('err'));
-                return;
+                if (config.onReAuth) {
+                    try {
+                        if (!reauthPromise) {
+                            reauthPromise = config.onReAuth().finally(() => {
+                                reauthPromise = null;
+                            });
+                        }
+                        const newToken = await reauthPromise;
+                        accessToken = newToken.accessToken;
+                        expiresAt = newToken.expiresAt;
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        config.onError(new Error(`Re-authentication failed: ${msg}`));
+                        throw new Error('Session expired and re-authentication failed. Please restart the proxy.');
+                    }
+                }
+                else {
+                    config.onReAuthNeeded();
+                    throw new Error('Token expired');
+                }
             }
             if (!method.success) {
                 config.onCall('unknown');
@@ -104,7 +122,6 @@ export function buildServer(config) {
             else {
                 config.onCall(method.data.method);
             }
-            done();
         },
         preHandler: (req, reply, done) => {
             if (accessToken === '') {
@@ -127,5 +144,7 @@ export function buildServer(config) {
             })
         }
     });
+    app.register(fastifyHttpProxy, proxyOptions('/'));
+    app.register(fastifyHttpProxy, proxyOptions('/rpc'));
     return app;
 }

package/dist/cli/{static → cli/static}/callback.html

@@ -45,7 +45,7 @@
       <div id="proxy-url" style="display: none" class="mt-6 text-blue-700 text-center">
         <img src="https://www.zksync.io/faq/faq-brackets.svg" alt="Success" class="h-12 w-auto mx-auto mb-3" />
         <span>You can now access your Prividium™ RPC proxy at: </span>
-        <span class="font-bold">http://127.0.0.1:24101/rpc</span>
+        <span class="font-bold">http://127.0.0.1:24101</span>
       </div>
       <pre
         id="error-details"

package/dist/cli/src/error-utils.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { UNAUTHORIZED_ERROR_CODE } from './rpc-error-codes.js';
+const jsonRpcErrorSchema = z.object({
+    error: z.object({
+        code: z.number(),
+        message: z.string().optional(),
+        data: z.unknown().optional()
+    })
+});
+const apiErrorSchema = z.object({
+    error: z.object({
+        code: z.string(),
+        message: z.string()
+    })
+});
+/**
+ * Checks if a Response contains a Prividium unauthorized/forbidden error.
+ */
+export async function hasPrividiumUnauthorizedError(response) {
+    try {
+        const clonedResponse = response.clone();
+        const parsed = jsonRpcErrorSchema.safeParse(await clonedResponse.json());
+        if (parsed.success) {
+            return parsed.data.error.code === UNAUTHORIZED_ERROR_CODE;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+export function isPrividiumUnauthorizedRpcError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const value = error;
+    if (value.code === UNAUTHORIZED_ERROR_CODE) {
+        return true;
+    }
+    return isPrividiumUnauthorizedRpcError(value.cause);
+}
+/**
+ * Extracts a human-readable error string from a failed HTTP response.
+ * Attempts to parse the server's `{ error: { code, message } }` JSON structure,
+ * falls back to plain text, and ultimately to status + statusText.
+ * Never throws — always returns a usable string.
+ */
+export async function extractResponseError(response) {
+    const base = `${response.status} ${response.statusText}`;
+    try {
+        const cloned = response.clone();
+        const text = await cloned.text();
+        if (!text) {
+            return base;
+        }
+        try {
+            const json = JSON.parse(text);
+            const parsed = apiErrorSchema.safeParse(json);
+            if (parsed.success) {
+                const { code, message } = parsed.data.error;
+                return `${base}: ${message} (${code})`;
+            }
+        }
+        catch {
+            // Not JSON
+        }
+        return `${base}: ${text}`;
+    }
+    catch {
+        // Body unreadable
+    }
+    return base;
+}