fix: authorize front-end RPC calls with the Prividium session token (#656)

# What ❔

Attaches the Prividium session token to the front-end's shared
`JsonRpcProvider`, so every RPC call the app makes is authorized as the
logged in user.

- `useContext.getL2Provider` builds the provider from a `FetchRequest`
carrying `Authorization: Bearer <session token>` when
`currentNetwork.prividium` is set. Public networks keep passing the bare
URL, unchanged.
- The provider cache now also resets on user change, not just network
change, so logging in or out rebuilds it with the right token.
- `useTokenOverview` sends the user's address as `from`, which the
Prividium RPC also requires.

## Why ❔

Max Total Supply is empty for every token on Prividium chains, reported
by Memento (PRIV-185).

The provider was constructed with a bare `rpcUrl`, so calls reached the
permissions API anonymous. `checkContractAccess` has no anonymous
branch, and `eth_call` is separately rejected when it carries no `from`,
so the call failed twice over before any permission rule was evaluated.
No admin-side permission change could have fixed it.

Doing this on the shared provider rather than per call fixes it
generically, since the explorer makes other front-end RPC reads that hit
the same wall.

With this in place an admin controls visibility from the admin panel by
adding `totalSupply()` to the token's contract or template function
permissions and picking who can call it (`All Users`, or a specific
role).

### Note on the first commit

The first commit proxied the read through a dedicated explorer API
endpoint. Per review that was too narrow, so it is fully reverted in the
second commit and the branch diff against `main` touches only the four
app files. The `prividium_tokenSupplyDisclosure` route was also
considered and skipped: `DISCLOSURE_METHODS_ENABLED` is off in every
environment, and it runs a trace plus storage proofs per call to produce
a value we would use unverified.

## Checklist

- [x] PR title corresponds to the body of PR (we generate changelog
entries from PRs).
- [x] Tests for the changes have been added / updated.
- [x] Documentation comments have been added / updated.

---------

Co-authored-by: romsters <petriv.roma@gmail.com>

Author: bxpana

packages/api/src/prividium.ts

@@ -3,6 +3,7 @@ import { ConfigService } from "@nestjs/config";
 import { AuthMiddleware } from "./middlewares/auth.middleware";
 import { AuthModule } from "./auth/auth.module";
 import { AuthController } from "./auth/auth.controller";
+import { RpcModule } from "./rpc/rpc.module";
 import { NoCacheMiddleware } from "./middlewares/no-cache.middleware";
 import { AddUserRolesPipe } from "./api/pipes/addUserRoles.pipe";
 import cookieSession from "cookie-session";
@@ -75,4 +76,4 @@ export function applyPrividiumMiddlewares(consumer: MiddlewareConsumer) {
   consumer.apply(AuthMiddleware).forRoutes("*");
 }
 
-export const PRIVIDIUM_MODULES = [AuthModule];
+export const PRIVIDIUM_MODULES = [AuthModule, RpcModule];

packages/api/src/rpc/rpc.controller.spec.ts

@@ -0,0 +1,74 @@
+import { mock } from "jest-mock-extended";
+import { ConfigService } from "@nestjs/config";
+import { UnauthorizedException } from "@nestjs/common";
+import { RpcController } from "./rpc.controller";
+import { PrividiumApiError } from "../errors/prividiumApiError";
+
+describe("RpcController", () => {
+  let controller: RpcController;
+  let configServiceMock: ConfigService;
+  let fetchSpy: jest.SpyInstance;
+
+  const configServiceValues = {
+    "prividium.permissionsApiUrl": "https://permissions-api.example.com",
+  };
+  const user = { address: "0x01", wallets: ["0x01"], token: "token1" };
+  const body = { jsonrpc: "2.0", id: 1, method: "eth_call", params: [] };
+
+  beforeEach(() => {
+    configServiceMock = mock<ConfigService>({
+      get: jest.fn().mockImplementation((key: string) => configServiceValues[key]),
+    });
+    controller = new RpcController(configServiceMock);
+    fetchSpy = jest.spyOn(global, "fetch");
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  it("forwards the request with the session token and returns the response", async () => {
+    fetchSpy.mockResolvedValueOnce({
+      status: 200,
+      ok: true,
+      json: () => Promise.resolve({ jsonrpc: "2.0", id: 1, result: "0x1" }),
+    });
+
+    expect(await controller.proxy(body, user)).toEqual({ jsonrpc: "2.0", id: 1, result: "0x1" });
+    expect(fetchSpy).toBeCalledWith(new URL("https://permissions-api.example.com/rpc"), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${user.token}`,
+      },
+      body: JSON.stringify(body),
+    });
+  });
+
+  it("rejects requests without a session", async () => {
+    await expect(controller.proxy(body, null)).rejects.toThrowError(UnauthorizedException);
+    expect(fetchSpy).not.toBeCalled();
+  });
+
+  it("throws when the permissions API rejects the token", async () => {
+    fetchSpy.mockResolvedValueOnce({ status: 401, ok: false, json: () => Promise.resolve({}) });
+
+    await expect(controller.proxy(body, user)).rejects.toThrowError(PrividiumApiError);
+  });
+
+  it("throws a bad gateway when the permissions API fails", async () => {
+    fetchSpy.mockResolvedValueOnce({ status: 500, ok: false, json: () => Promise.resolve({}) });
+
+    await expect(controller.proxy(body, user)).rejects.toThrowError(expect.objectContaining({ status: 502 }) as Error);
+  });
+
+  it("throws a bad gateway when the response is not JSON", async () => {
+    fetchSpy.mockResolvedValueOnce({
+      status: 200,
+      ok: true,
+      json: () => Promise.reject(new SyntaxError("Unexpected token < in JSON")),
+    });
+
+    await expect(controller.proxy(body, user)).rejects.toThrowError(expect.objectContaining({ status: 502 }) as Error);
+  });
+});

packages/api/src/rpc/rpc.controller.ts

@@ -0,0 +1,51 @@
+import { Body, Controller, Header, Post, UnauthorizedException } from "@nestjs/common";
+import { ApiExcludeController, ApiOkResponse, ApiTags } from "@nestjs/swagger";
+import { ConfigService } from "@nestjs/config";
+import { swagger } from "../config/featureFlags";
+import { PrividiumApiError } from "../errors/prividiumApiError";
+import { User, UserParam } from "../user/user.decorator";
+
+const entityName = "rpc";
+
+@ApiTags("RPC BFF")
+@ApiExcludeController(!swagger.bffEnabled)
+@Controller(entityName)
+export class RpcController {
+  constructor(private readonly configService: ConfigService) {}
+
+  // Prividium authorizes every RPC call against the caller and only the session holds the
+  // user's permissions API token, so the app's RPC calls are made on its behalf here.
+  @Post("")
+  @Header("Content-Type", "application/json")
+  @ApiOkResponse({ description: "JSON-RPC response returned by the permissions API" })
+  public async proxy(@Body() body: unknown, @User() user: UserParam): Promise<unknown> {
+    if (!user) {
+      throw new UnauthorizedException({ message: "Unauthorized request" });
+    }
+
+    const response = await fetch(new URL("/rpc", this.configService.get("prividium.permissionsApiUrl")), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${user.token}`,
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (response.status === 401 || response.status === 403) {
+      throw new PrividiumApiError("Invalid or expired token", 401);
+    }
+
+    // A JSON-RPC error is carried in a 2xx body, so any other status is a transport failure.
+    // Without this an upstream 5xx is returned to the app as a 200 with a body ethers cannot parse.
+    if (!response.ok) {
+      throw new PrividiumApiError("Invalid response from permissions API", 502);
+    }
+
+    try {
+      return await response.json();
+    } catch {
+      throw new PrividiumApiError("Invalid response from permissions API", 502);
+    }
+  }
+}

packages/api/src/rpc/rpc.module.ts

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common";
+import { RpcController } from "./rpc.controller";
+
+@Module({
+  controllers: [RpcController],
+})
+export class RpcModule {}

packages/app/src/composables/useContext.ts

@@ -1,7 +1,7 @@
 import { computed, type ComputedRef, type Ref, ref, watch } from "vue";
 
 import { useStorage } from "@vueuse/core";
-import { JsonRpcProvider } from "ethers";
+import { FetchRequest, JsonRpcProvider, makeError } from "ethers";
 
 import useEnvironmentConfig from "./useEnvironmentConfig";
 import { DEFAULT_NETWORK } from "./useRuntimeConfig";
@@ -31,6 +31,59 @@ export type Context = {
   isGatewaySettlementChain: (chainId: number | null) => boolean;
 };
 
+// Prividium authorizes every RPC call against the caller, and only the explorer API session
+// holds the user's token, so RPC calls go through the API instead of straight to the RPC.
+// The session cookie is set on the API origin and ethers does not send cross-origin
+// credentials, so the request is made with a fetch that includes them.
+function getRpcRequest(network: NetworkConfig) {
+  if (!network.prividium) {
+    return network.rpcUrl;
+  }
+
+  const request = new FetchRequest(`${network.apiUrl}/rpc`);
+  // Overriding getUrlFunc replaces ethers' own fetch, which arms `req.timeout` and forwards
+  // cancellation, so both are reproduced here to keep requests bounded and abortable.
+  request.getUrlFunc = async (req, signal) => {
+    const controller = new AbortController();
+    let abortError: Error | null = null;
+    const timer = setTimeout(() => {
+      abortError = makeError("request timeout", "TIMEOUT");
+      controller.abort();
+    }, req.timeout);
+    signal?.addListener(() => {
+      abortError = makeError("request cancelled", "CANCELLED");
+      controller.abort();
+    });
+
+    let response: Response;
+    try {
+      response = await fetch(req.url, {
+        method: req.method,
+        headers: req.headers,
+        body: req.body,
+        credentials: "include",
+        signal: controller.signal,
+      });
+    } catch (error) {
+      throw abortError ?? error;
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const headers: Record<string, string> = {};
+    response.headers.forEach((value, key) => {
+      headers[key.toLowerCase()] = value;
+    });
+    return {
+      statusCode: response.status,
+      statusMessage: response.statusText,
+      headers,
+      body: new Uint8Array(await response.arrayBuffer()),
+    };
+  };
+  return request;
+}
+
 let l2Provider: JsonRpcProvider | null;
 export default (): Context => {
   const environmentConfig = useEnvironmentConfig();
@@ -78,7 +131,7 @@ export default (): Context => {
 
   function getL2Provider() {
     if (!l2Provider) {
-      l2Provider = new JsonRpcProvider(currentNetwork.value.rpcUrl, currentNetwork.value.l2ChainId, {
+      l2Provider = new JsonRpcProvider(getRpcRequest(currentNetwork.value), currentNetwork.value.l2ChainId, {
         staticNetwork: true,
       });
     }

packages/app/tests/composables/useContext.spec.ts

@@ -89,4 +89,77 @@ describe("useContext:", () => {
       });
     });
   });
+
+  describe("getL2Provider:", () => {
+    const PUBLIC_NETWORK = { ...TESTNET_NETWORK, name: "public", rpcUrl: "https://rpc.example.com" };
+    const PRIVIDIUM_NETWORK = {
+      ...TESTNET_NETWORK,
+      name: "prividium",
+      prividium: true,
+      apiUrl: "https://api.example.com",
+      rpcUrl: "https://rpc.example.com",
+    };
+
+    const buildContext = (network: typeof TESTNET_NETWORK) => {
+      const mockStorage = vi.spyOn(Storage.prototype, "getItem").mockReturnValue(network.name);
+      const mockEnvironmentConfig = vi.spyOn(useEnvironmentConfig, "default").mockReturnValue({
+        networks: computed(() => [network]),
+        baseTokenAddress: computed(() => "0x000000000000000000000000000000000000800A"),
+      });
+      const context = useContext.default();
+      context.identifyNetwork();
+      return { context, restore: () => [mockStorage, mockEnvironmentConfig].forEach((m) => m.mockRestore()) };
+    };
+
+    it("connects straight to the RPC on a public network", () => {
+      const { context, restore } = buildContext(PUBLIC_NETWORK);
+
+      expect(context.getL2Provider()._getConnection().url).toBe("https://rpc.example.com");
+      restore();
+    });
+
+    it("connects through the explorer API on a Prividium network", () => {
+      const { context, restore } = buildContext(PRIVIDIUM_NETWORK);
+
+      expect(context.getL2Provider()._getConnection().url).toBe("https://api.example.com/rpc");
+      restore();
+    });
+
+    it("sends session credentials and an abort signal on a Prividium network", async () => {
+      const { context, restore } = buildContext(PRIVIDIUM_NETWORK);
+      const fetchMock = vi.spyOn(global, "fetch").mockResolvedValue({
+        status: 200,
+        statusText: "OK",
+        headers: new Headers(),
+        arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+      } as unknown as Response);
+
+      const request = context.getL2Provider()._getConnection();
+      await request.getUrlFunc(request);
+
+      expect(fetchMock).toBeCalledWith(
+        "https://api.example.com/rpc",
+        expect.objectContaining({ credentials: "include", signal: expect.any(AbortSignal) })
+      );
+      fetchMock.mockRestore();
+      restore();
+    });
+
+    it("aborts a Prividium request that exceeds the request timeout", async () => {
+      const { context, restore } = buildContext(PRIVIDIUM_NETWORK);
+      const fetchMock = vi.spyOn(global, "fetch").mockImplementation(
+        (_url, init) =>
+          new Promise((_resolve, reject) => {
+            (init as RequestInit).signal?.addEventListener("abort", () => reject(new Error("aborted")));
+          })
+      );
+
+      const request = context.getL2Provider()._getConnection();
+      request.timeout = 1;
+
+      await expect(request.getUrlFunc(request)).rejects.toThrowError(/timeout/);
+      fetchMock.mockRestore();
+      restore();
+    });
+  });
 });