prividium 0.21.1 → 0.22.0

package/README.md

@@ -414,7 +414,68 @@ interface PrividiumSiweConfig {
 ```
 
 **Returns:** `PrividiumSiweChain` - with all the same methods as `PrividiumChain` (except `addNetworkToWallet` which is
-browser-only), plus `address` (the wallet address derived from the account).
+browser-only), plus `address` (the wallet address derived from the account) and an `admin` namespace for permissions-API
+administration operations.
+
+### Admin API: `prividium.admin.*`
+
+The `admin` namespace on a `PrividiumSiweChain` instance wraps permissions-API endpoints that require admin
+authorization. Calls go through the same authenticated transport as the chain itself, so session refresh and 401 retries
+are handled automatically.
+
+```typescript
+// Look up a user by id, then associate additional wallet addresses
+const user = await prividium.admin.users.getById('usr_abc123');
+const merged = [...new Set([...user.wallets.map((w) => w.walletAddress), '0xNEW_WALLET_ADDRESS'])];
+await prividium.admin.users.update(user.id, { wallets: merged });
+
+// Whitelist a freshly deployed contract against a permissions template
+await prividium.admin.contracts.create({
+  contractAddress: '0xCONTRACT_ADDRESS',
+  templateKey: 'erc20-token',
+  abi: '[]',
+  name: null,
+  description: null,
+  discloseErc20TotalSupply: false,
+  discloseBytecode: false
+});
+```
+
+**Methods:**
+
+| Method                           | HTTP   | Endpoint         | Description                                                         |
+| -------------------------------- | ------ | ---------------- | ------------------------------------------------------------------- |
+| `admin.users.getById(id)`        | `GET`  | `/api/users/:id` | Fetch a single user, including roles and wallet records.            |
+| `admin.users.update(id, params)` | `PUT`  | `/api/users/:id` | Replace a user's editable fields (display name, roles, wallets, …). |
+| `admin.contracts.create(params)` | `POST` | `/api/contracts` | Whitelist a contract address, optionally linked to a template.      |
+
+Types are exported from `prividium/siwe`: `AdminUser`, `AdminUserUpdate`, `AdminContract`, `AdminContractCreate`. Calls
+throw on non-2xx responses; treat them like any other awaited fetch. Failed authorization (`401` / `403`) follows the
+normal session-refresh path described in [Auto-Reauthentication](#auto-reauthentication).
+
+### Verifying a user access token: `verifyUserAccessToken(token, options)`
+
+Stateless helper for backend services that need to validate an end-user's Prividium access token (e.g. a token forwarded
+from a frontend) without setting up a SIWE chain. Calls `GET /api/profiles/me` with the bearer token and returns the
+verified user id, or a typed error.
+
+```typescript
+import { verifyUserAccessToken } from 'prividium/siwe';
+
+const result = await verifyUserAccessToken(req.headers.authorization, {
+  apiUrl: 'https://permissions.prividium.io'
+});
+
+if (!result.valid) {
+  // result.error is 'network_error' | 'invalid_token' | 'server_error'
+  return res.status(401).json({ error: result.error });
+}
+
+// result.userId is the Prividium user id corresponding to the token
+req.userId = result.userId;
+```
+
+The helper accepts either a raw token (`abc123…`) or a full `Bearer abc123…` header and won't double-prefix.
 
 ### Auto-Reauthentication
 

package/dist/sdk/admin-api/contracts.d.ts

@@ -0,0 +1,9 @@
+import type { ApiCaller } from '../chain-core.js';
+import type { AdminContract, AdminContractCreate } from './types.js';
+export interface ContractsAdminMethods {
+    create(params: AdminContractCreate): Promise<AdminContract>;
+}
+export declare function createContractsAdminMethods(deps: {
+    prividiumApiCall: ApiCaller;
+    prividiumApiBaseUrl: string;
+}): ContractsAdminMethods;

package/dist/sdk/admin-api/contracts.js

@@ -0,0 +1,10 @@
+import { adminContractSchema } from './schemas.js';
+export function createContractsAdminMethods(deps) {
+    const { prividiumApiCall, prividiumApiBaseUrl } = deps;
+    const url = `${prividiumApiBaseUrl}/api/contracts`;
+    return {
+        async create(params) {
+            return prividiumApiCall(adminContractSchema, url, 'POST', JSON.stringify(params));
+        }
+    };
+}

package/dist/sdk/admin-api/index.d.ts

@@ -0,0 +1,14 @@
+import type { ApiCaller } from '../chain-core.js';
+import { type ContractsAdminMethods } from './contracts.js';
+import { type UsersAdminMethods } from './users.js';
+export interface AdminMethods {
+    users: UsersAdminMethods;
+    contracts: ContractsAdminMethods;
+}
+export declare function createAdminMethods(deps: {
+    prividiumApiCall: ApiCaller;
+    prividiumApiBaseUrl: string;
+}): AdminMethods;
+export type { ContractsAdminMethods } from './contracts.js';
+export type { AdminContract, AdminContractCreate, AdminUser, AdminUserUpdate } from './types.js';
+export type { UsersAdminMethods } from './users.js';

package/dist/sdk/admin-api/index.js

@@ -0,0 +1,8 @@
+import { createContractsAdminMethods } from './contracts.js';
+import { createUsersAdminMethods } from './users.js';
+export function createAdminMethods(deps) {
+    return {
+        users: createUsersAdminMethods(deps),
+        contracts: createContractsAdminMethods(deps)
+    };
+}

package/dist/sdk/admin-api/schemas.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+export declare const adminUserSchema: z.ZodObject<{
+    id: z.ZodString;
+    oidcSub: z.ZodNullable<z.ZodString>;
+    displayName: z.ZodString;
+    source: z.ZodEnum<{
+        oidc: "oidc";
+        adminPanel: "adminPanel";
+        tenant: "tenant";
+        crypto_native: "crypto_native";
+        m2m_app: "m2m_app";
+    }>;
+    organizationId: z.ZodNullable<z.ZodString>;
+    walletToken: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    organization: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    roles: z.ZodArray<z.ZodObject<{
+        roleName: z.ZodString;
+        systemPermissions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            contract_deployment: "contract_deployment";
+            full_sequencer_rpc_access: "full_sequencer_rpc_access";
+            full_read_access: "full_read_access";
+            admin_read: "admin_read";
+            org_users_manage: "org_users_manage";
+            org_wallets_manage: "org_wallets_manage";
+            org_rpc_access: "org_rpc_access";
+            rpc_read_eth_getBlockByNumber: "rpc_read_eth_getBlockByNumber";
+            rpc_read_eth_getLogs: "rpc_read_eth_getLogs";
+            rpc_read_eth_getTransactionByHash: "rpc_read_eth_getTransactionByHash";
+            rpc_read_eth_getTransactionReceipt: "rpc_read_eth_getTransactionReceipt";
+            check_user_read_access: "check_user_read_access";
+            contract_metadata_read: "contract_metadata_read";
+        }>>>;
+        isSystemRole: z.ZodOptional<z.ZodBoolean>;
+        createdAt: z.ZodOptional<z.ZodString>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    wallets: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        walletAddress: z.ZodString;
+        userId: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const adminContractSchema: z.ZodObject<{
+    contractAddress: z.ZodString;
+    abi: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    discloseErc20TotalSupply: z.ZodBoolean;
+    discloseBytecode: z.ZodBoolean;
+    templateId: z.ZodNullable<z.ZodNumber>;
+    isSystemContract: z.ZodBoolean;
+    disclosedAddresses: z.ZodArray<z.ZodObject<{
+        address: z.ZodString;
+    }, z.core.$strip>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;

package/dist/sdk/admin-api/schemas.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+const systemPermissionSchema = z.enum([
+    'contract_deployment',
+    'full_sequencer_rpc_access',
+    'full_read_access',
+    'admin_read',
+    'org_users_manage',
+    'org_wallets_manage',
+    'org_rpc_access',
+    'rpc_read_eth_getBlockByNumber',
+    'rpc_read_eth_getLogs',
+    'rpc_read_eth_getTransactionByHash',
+    'rpc_read_eth_getTransactionReceipt',
+    'check_user_read_access',
+    'contract_metadata_read'
+]);
+const userWalletSchema = z.object({
+    id: z.number(),
+    walletAddress: z.string(),
+    userId: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string()
+});
+const userRoleSchema = z.object({
+    roleName: z.string(),
+    systemPermissions: z.array(systemPermissionSchema).optional(),
+    isSystemRole: z.boolean().optional(),
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional()
+});
+const userOrganizationSchema = z.object({
+    id: z.string(),
+    name: z.string()
+});
+const userSourceSchema = z.enum(['oidc', 'adminPanel', 'tenant', 'crypto_native', 'm2m_app']);
+export const adminUserSchema = z.object({
+    id: z.string(),
+    oidcSub: z.string().nullable(),
+    displayName: z.string(),
+    source: userSourceSchema,
+    organizationId: z.string().nullable(),
+    walletToken: z.string().nullable(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    organization: userOrganizationSchema.nullable(),
+    roles: z.array(userRoleSchema),
+    wallets: z.array(userWalletSchema)
+});
+const disclosedAddressSchema = z.object({ address: z.string() });
+export const adminContractSchema = z.object({
+    contractAddress: z.string(),
+    abi: z.string(),
+    name: z.string().nullable(),
+    description: z.string().nullable(),
+    discloseErc20TotalSupply: z.boolean(),
+    discloseBytecode: z.boolean(),
+    templateId: z.number().nullable(),
+    isSystemContract: z.boolean(),
+    disclosedAddresses: z.array(disclosedAddressSchema),
+    createdAt: z.string(),
+    updatedAt: z.string()
+});

package/dist/sdk/admin-api/types.d.ts

@@ -0,0 +1,71 @@
+export type AdminUserSource = 'oidc' | 'adminPanel' | 'tenant' | 'crypto_native' | 'm2m_app';
+export type AdminSystemPermission = 'contract_deployment' | 'full_sequencer_rpc_access' | 'full_read_access' | 'admin_read' | 'org_users_manage' | 'org_wallets_manage' | 'org_rpc_access' | 'rpc_read_eth_getBlockByNumber' | 'rpc_read_eth_getLogs' | 'rpc_read_eth_getTransactionByHash' | 'rpc_read_eth_getTransactionReceipt' | 'check_user_read_access' | 'contract_metadata_read';
+export interface AdminUserRole {
+    roleName: string;
+    systemPermissions?: Array<AdminSystemPermission>;
+    isSystemRole?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface AdminUserWallet {
+    id: number;
+    walletAddress: string;
+    userId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AdminUserOrganization {
+    id: string;
+    name: string;
+}
+export interface AdminUser {
+    id: string;
+    oidcSub: string | null;
+    displayName: string;
+    source: AdminUserSource;
+    organizationId: string | null;
+    walletToken: string | null;
+    createdAt: string;
+    updatedAt: string;
+    organization: AdminUserOrganization | null;
+    roles: Array<AdminUserRole>;
+    wallets: Array<AdminUserWallet>;
+}
+export interface AdminUserUpdate {
+    id?: string;
+    oidcSub?: string | null;
+    displayName?: string;
+    source?: AdminUserSource;
+    walletToken?: string | null;
+    createdAt?: unknown;
+    updatedAt?: unknown;
+    roles?: Array<string>;
+    wallets?: Array<string>;
+}
+export interface AdminDisclosedAddress {
+    address: string;
+}
+export interface AdminContract {
+    contractAddress: string;
+    abi: string;
+    name: string | null;
+    description: string | null;
+    discloseErc20TotalSupply: boolean;
+    discloseBytecode: boolean;
+    templateId: number | null;
+    isSystemContract: boolean;
+    disclosedAddresses: Array<AdminDisclosedAddress>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AdminContractCreate {
+    contractAddress: string;
+    abi: string;
+    name: string | null;
+    description: string | null;
+    discloseErc20TotalSupply?: boolean;
+    discloseBytecode?: boolean;
+    disclosedAddresses?: Array<AdminDisclosedAddress>;
+    templateId?: number | null;
+    templateKey?: string | null;
+}

package/dist/sdk/admin-api/types.js

@@ -0,0 +1,5 @@
+// Types mirror the permissions-api OpenAPI spec at /api/users/{id} and /api/contracts.
+// Hand-written so the published declarations are self-contained. The alignment test at
+// src/admin-api/types-alignment.test.ts cross-checks these against the workspace
+// OpenAPI-generated types and fails typecheck on drift.
+export {};

package/dist/sdk/admin-api/users.d.ts

@@ -0,0 +1,10 @@
+import type { ApiCaller } from '../chain-core.js';
+import type { AdminUser, AdminUserUpdate } from './types.js';
+export interface UsersAdminMethods {
+    getById(userId: string): Promise<AdminUser>;
+    update(userId: string, params: AdminUserUpdate): Promise<AdminUser>;
+}
+export declare function createUsersAdminMethods(deps: {
+    prividiumApiCall: ApiCaller;
+    prividiumApiBaseUrl: string;
+}): UsersAdminMethods;

package/dist/sdk/admin-api/users.js

@@ -0,0 +1,13 @@
+import { adminUserSchema } from './schemas.js';
+export function createUsersAdminMethods(deps) {
+    const { prividiumApiCall, prividiumApiBaseUrl } = deps;
+    const baseUrl = (id) => `${prividiumApiBaseUrl}/api/users/${encodeURIComponent(id)}`;
+    return {
+        async getById(userId) {
+            return prividiumApiCall(adminUserSchema, baseUrl(userId), 'GET');
+        },
+        async update(userId, params) {
+            return prividiumApiCall(adminUserSchema, baseUrl(userId), 'PUT', JSON.stringify(params));
+        }
+    };
+}

package/dist/sdk/chain-core.d.ts

@@ -7,7 +7,8 @@ export declare function buildChainObject(config: {
     chain: Omit<Chain, 'rpcUrls'>;
     prividiumApiBaseUrl: string;
 }): Chain;
-export type ApiCaller = <Schema extends ZodType>(schema: Schema, url: string, method: 'GET' | 'POST', body?: string) => Promise<z.infer<Schema>>;
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type ApiCaller = <Schema extends ZodType>(schema: Schema, url: string, method: HttpMethod, body?: string) => Promise<z.infer<Schema>>;
 export declare function createApiMethods(deps: {
     prividiumApiCall: ApiCaller;
     prividiumApiBaseUrl: string;

package/dist/sdk/index.d.ts

@@ -7,3 +7,5 @@ export { LocalStorage, TokenManager } from './storage.js';
 export { generateRandomState } from './token-utils.js';
 export type { AddNetworkParams, ContractAbiResponse, PopupOptions, PrividiumChain, PrividiumConfig, Storage, TokenData, UserProfile, UserRole } from './types.js';
 export { AUTH_ERRORS, STORAGE_KEYS } from './types.js';
+export type { UserTokenVerifyError, UserTokenVerifyResult, VerifyUserAccessTokenOptions } from './verify-user-access-token.js';
+export { verifyUserAccessToken } from './verify-user-access-token.js';

package/dist/sdk/index.js

@@ -6,3 +6,4 @@ export * from './selective-disclosure/index.js';
 export { LocalStorage, TokenManager } from './storage.js';
 export { generateRandomState } from './token-utils.js';
 export { AUTH_ERRORS, STORAGE_KEYS } from './types.js';
+export { verifyUserAccessToken } from './verify-user-access-token.js';

package/dist/sdk/siwe-chain.d.ts

@@ -1,4 +1,5 @@
 import { type Address, type Chain, type LocalAccount, type Transport } from 'viem';
+import { type AdminMethods } from './admin-api/index.js';
 import type { AuthorizeTransactionParams, AuthorizeTransactionResponse, Storage, TokenData, UserProfile } from './types.js';
 export interface PrividiumSiweConfig {
     chain: Omit<Chain, 'rpcUrls'>;
@@ -24,5 +25,6 @@ export interface PrividiumSiweChain {
     getWalletRpcUrl(): Promise<string>;
     invalidateWalletToken(): Promise<string>;
     authorizeTransaction(params: AuthorizeTransactionParams): Promise<AuthorizeTransactionResponse>;
+    admin: AdminMethods;
 }
 export declare function createPrividiumSiweChain(config: PrividiumSiweConfig): PrividiumSiweChain;

package/dist/sdk/siwe-chain.js

@@ -1,4 +1,5 @@
 import { http } from 'viem';
+import { createAdminMethods } from './admin-api/index.js';
 import { buildChainObject, createApiMethods, rpcUrl } from './chain-core.js';
 import { extractResponseError, isPrividiumUnauthorizedRpcError } from './error-utils.js';
 import { PrividiumSessionError } from './errors.js';
@@ -152,6 +153,7 @@ export function createPrividiumSiweChain(config) {
         };
     };
     const apiMethods = createApiMethods({ prividiumApiCall, prividiumApiBaseUrl: config.prividiumApiBaseUrl });
+    const admin = createAdminMethods({ prividiumApiCall, prividiumApiBaseUrl: config.prividiumApiBaseUrl });
     return {
         chain: buildChainObject(config),
         transport,
@@ -170,6 +172,7 @@ export function createPrividiumSiweChain(config) {
         getWalletToken: apiMethods.getWalletToken,
         getWalletRpcUrl: apiMethods.getWalletRpcUrl,
         invalidateWalletToken: apiMethods.invalidateWalletToken,
-        authorizeTransaction: apiMethods.authorizeTransaction
+        authorizeTransaction: apiMethods.authorizeTransaction,
+        admin
     };
 }

package/dist/sdk/siwe.d.ts

@@ -1,3 +1,4 @@
+export type { AdminContract, AdminContractCreate, AdminMethods, AdminUser, AdminUserUpdate, ContractsAdminMethods, UsersAdminMethods } from './admin-api/index.js';
 export { createPrividiumClient } from './create-prividium-client.js';
 export { MemoryStorage } from './memory-storage.js';
 export { FORBIDDEN_ERROR_CODE, METHOD_NOT_FOUND_ERROR_CODE, UNAUTHORIZED_ERROR_CODE } from './rpc-error-codes.js';
@@ -8,3 +9,5 @@ export { createPrividiumSiweChain } from './siwe-chain.js';
 export { TokenManager } from './storage.js';
 export type { AuthorizeTransactionParams, AuthorizeTransactionResponse, Storage, TokenData, UserProfile, UserRole } from './types.js';
 export { AUTH_ERRORS } from './types.js';
+export type { UserTokenVerifyError, UserTokenVerifyResult, VerifyUserAccessTokenOptions } from './verify-user-access-token.js';
+export { verifyUserAccessToken } from './verify-user-access-token.js';

package/dist/sdk/siwe.js

@@ -9,3 +9,4 @@ export { SiweAuth } from './siwe-auth.js';
 export { createPrividiumSiweChain } from './siwe-chain.js';
 export { TokenManager } from './storage.js';
 export { AUTH_ERRORS } from './types.js';
+export { verifyUserAccessToken } from './verify-user-access-token.js';

package/dist/sdk/verify-user-access-token.d.ts

@@ -0,0 +1,15 @@
+export type UserTokenVerifyError = 'network_error' | 'invalid_token' | 'server_error';
+export type UserTokenVerifyResult = {
+    valid: true;
+    userId: string;
+} | {
+    valid: false;
+    error: UserTokenVerifyError;
+    cause?: unknown;
+};
+export interface VerifyUserAccessTokenOptions {
+    apiUrl: string;
+    /** Called with the underlying Error before returning a `{ valid: false }` result. */
+    onError?: (error: unknown) => void;
+}
+export declare function verifyUserAccessToken(token: string, options: VerifyUserAccessTokenOptions): Promise<UserTokenVerifyResult>;

package/dist/sdk/verify-user-access-token.js

@@ -0,0 +1,35 @@
+export async function verifyUserAccessToken(token, options) {
+    const authorizationHeader = token.startsWith('Bearer ') ? token : `Bearer ${token}`;
+    let response;
+    try {
+        response = await fetch(new URL('/api/profiles/me', options.apiUrl), {
+            method: 'GET',
+            headers: {
+                Authorization: authorizationHeader,
+                'Content-Type': 'application/json'
+            }
+        });
+    }
+    catch (cause) {
+        options.onError?.(cause);
+        return { valid: false, error: 'network_error', cause };
+    }
+    if (!response.ok) {
+        if (response.status === 401 || response.status === 403) {
+            return { valid: false, error: 'invalid_token' };
+        }
+        return { valid: false, error: 'server_error' };
+    }
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch (cause) {
+        options.onError?.(cause);
+        return { valid: false, error: 'server_error', cause };
+    }
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.id !== 'string') {
+        return { valid: false, error: 'invalid_token' };
+    }
+    return { valid: true, userId: parsed.id };
+}