@canton-network/core-wallet-auth 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# Wallet Auth
+
+This workspace contains the authentication logic and interfaces used by the Splice Wallet Kernel.
+It provides abstractions for authentication services, user identity management, and integration points for different identity providers (IDPs), such as password-based and OAuth2/OIDC-based authentication.
+
+## Installation
+
+This package requires [NodeJS](https://nodejs.org/) v16 or higher and can be added to your project using:
+
+```sh
+npm install @canton-network/core-wallet-auth --save
+```
+
+or
+
+```sh
+yarn add @canton-network/core-wallet-auth
+```
+
+## Interfaces
+
+This workspace defines several core interfaces for authentication.
+
+### [AuthContext](./src/AuthService.ts)
+
+Represents the authentication context for a user, including their unique user ID and the associated access token.
+
+### [AuthAware](./src/AuthService.ts)
+
+Provides a pattern for classes or services that are aware of authentication context.
+It exposes the current `authContext` and a method `withAuthContext` to create a new instance with a specific authentication context.
+An example the application of this pattern can be seen in the [StoreInternal](../wallet-store/src/StoreInternal.ts).
+
+### [AuthService](./src/AuthService.ts)
+
+Defines the contract for authentication services.
+The `verifyToken` method takes an access token and returns an `AuthContext` if the token is valid, or `undefined` otherwise.
+
+## JWT Implementation
+
+For JWT-based authentication, see the [`JwtAuthService`](../clients/remote/src/auth/JwtAuthService.ts) implementation.
+This service verifies JWT tokens using remote JWK sets and integrates with the wallet kernel's network configuration to dynamically resolve the appropriate identity provider for each request.
+
+It is important to note that, since the wallet kernel supports multiple identity providers (IDPs), the token issuer (iss) is used as the unique identifier for each IDP.
+This component therefore collaborates with the [Store](../wallet-store/src/Store.ts), which enables lookup of the configured IDP based on the issuer value.

package/dist/AuthService.d.ts

@@ -0,0 +1,13 @@
+export type UserId = string;
+export interface AuthContext {
+    userId: UserId;
+    accessToken: string;
+}
+export interface AuthService {
+    verifyToken(accessToken?: string): Promise<AuthContext | undefined>;
+}
+export interface AuthAware<T> {
+    authContext: AuthContext | undefined;
+    withAuthContext: (context?: AuthContext) => T;
+}
+//# sourceMappingURL=AuthService.d.ts.map

package/dist/AuthService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthService.d.ts","sourceRoot":"","sources":["../src/AuthService.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GAAG,MAAM,CAAA;AAE3B,MAAM,WAAW,WAAW;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,WAAW;IACxB,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAA;CACtE;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IACxB,WAAW,EAAE,WAAW,GAAG,SAAS,CAAA;IACpC,eAAe,EAAE,CAAC,OAAO,CAAC,EAAE,WAAW,KAAK,CAAC,CAAA;CAChD"}

package/dist/AuthService.js

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

package/dist/auth-service.d.ts

@@ -0,0 +1,13 @@
+export type UserId = string;
+export interface AuthContext {
+    userId: UserId;
+    accessToken: string;
+}
+export interface AuthService {
+    verifyToken(accessToken?: string): Promise<AuthContext | undefined>;
+}
+export interface AuthAware<T> {
+    authContext: AuthContext | undefined;
+    withAuthContext: (context?: AuthContext) => T;
+}
+//# sourceMappingURL=auth-service.d.ts.map

package/dist/auth-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-service.d.ts","sourceRoot":"","sources":["../src/auth-service.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GAAG,MAAM,CAAA;AAE3B,MAAM,WAAW,WAAW;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,WAAW;IACxB,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAA;CACtE;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IACxB,WAAW,EAAE,WAAW,GAAG,SAAS,CAAA;IACpC,eAAe,EAAE,CAAC,OAAO,CAAC,EAAE,WAAW,KAAK,CAAC,CAAA;CAChD"}

package/dist/auth-service.js

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

package/dist/client-credentials-service.d.ts

@@ -0,0 +1,28 @@
+import { Logger } from '@canton-network/core-types';
+export interface OIDCConfig {
+    token_endpoint: string;
+}
+export interface ClientCredentials {
+    clientId: string;
+    clientSecret: string;
+    scope: string | undefined;
+    audience: string | undefined;
+}
+export declare class ClientCredentialsService {
+    private configUrl;
+    private logger;
+    constructor(configUrl: string, logger: Logger | undefined);
+    /**
+     * Fetches the JWT token (M2M) using client credentials.
+     *
+     * @returns The JWT access token as a string.
+     * @throws If fetching the token fails or the response is invalid.
+     */
+    fetchToken(credentials: ClientCredentials): Promise<string>;
+    fetchTokenEndpoint(tokenEndpoint: string, credentials: ClientCredentials): Promise<Response>;
+    getOIDCConfig(url: string): Promise<OIDCConfig>;
+}
+export declare const clientCredentialsService: (configUrl: string, logger: Logger | undefined) => {
+    fetchToken: (credentials: ClientCredentials) => Promise<string>;
+};
+//# sourceMappingURL=client-credentials-service.d.ts.map

package/dist/client-credentials-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-credentials-service.d.ts","sourceRoot":"","sources":["../src/client-credentials-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAA;AAEnD,MAAM,WAAW,UAAU;IACvB,cAAc,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/B;AAED,qBAAa,wBAAwB;IAE7B,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,MAAM;gBADN,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,SAAS;IAGtC;;;;;OAKG;IACG,UAAU,CAAC,WAAW,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IA2B3D,kBAAkB,CACpB,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,iBAAiB,GAC/B,OAAO,CAAC,QAAQ,CAAC;IA4Bd,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAcxD;AAED,eAAO,MAAM,wBAAwB,GACjC,WAAW,MAAM,EACjB,QAAQ,MAAM,GAAG,SAAS;8BAEM,iBAAiB;CAEnD,CAAA"}

package/dist/client-credentials-service.js

@@ -0,0 +1,62 @@
+export class ClientCredentialsService {
+    configUrl;
+    logger;
+    constructor(configUrl, logger) {
+        this.configUrl = configUrl;
+        this.logger = logger;
+    }
+    /**
+     * Fetches the JWT token (M2M) using client credentials.
+     *
+     * @returns The JWT access token as a string.
+     * @throws If fetching the token fails or the response is invalid.
+     */
+    async fetchToken(credentials) {
+        try {
+            const oidcConfig = await this.getOIDCConfig(this.configUrl);
+            this.logger?.debug({ oidcConfig }, 'Fetched OIDC config');
+            const res = await this.fetchTokenEndpoint(oidcConfig.token_endpoint, credentials);
+            const json = await res.json();
+            this.logger?.info({ response: json }, `Fetched admin token for clientId: ${credentials.clientId}`);
+            if (!json.access_token) {
+                throw new Error('No access_token in token endpoint response');
+            }
+            return json.access_token;
+        }
+        catch (error) {
+            this.logger?.error({ err: error }, 'Failed to fetch admin token');
+            throw error;
+        }
+    }
+    async fetchTokenEndpoint(tokenEndpoint, credentials) {
+        const params = new URLSearchParams({
+            grant_type: 'client_credentials',
+            client_id: credentials.clientId,
+            client_secret: credentials.clientSecret,
+            scope: credentials.scope ?? '',
+            audience: credentials.audience ?? '',
+        });
+        const res = await fetch(tokenEndpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: params.toString(),
+        });
+        if (!res.ok) {
+            this.logger?.error({ status: res.status, statusText: res.statusText }, 'Token endpoint error');
+            throw new Error(`Token endpoint error: ${res.status} ${res.statusText}`);
+        }
+        return res;
+    }
+    async getOIDCConfig(url) {
+        const res = await fetch(url);
+        if (!res.ok) {
+            const text = await res.text();
+            this.logger?.error({ status: res.status, statusText: res.statusText, body: text }, 'Failed to fetch OIDC config');
+            throw new Error(`OIDC config error: ${res.status} ${res.statusText}`);
+        }
+        return res.json();
+    }
+}
+export const clientCredentialsService = (configUrl, logger) => ({
+    fetchToken: async (credentials) => new ClientCredentialsService(configUrl, logger).fetchToken(credentials),
+});

package/dist/client-credentials.service.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client-credentials.service.test.d.ts.map

package/dist/client-credentials.service.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-credentials.service.test.d.ts","sourceRoot":"","sources":["../src/client-credentials.service.test.ts"],"names":[],"mappings":""}

package/dist/client-credentials.service.test.js

@@ -0,0 +1,53 @@
+import { jest } from '@jest/globals';
+import { ClientCredentialsService, } from './client-credentials-service.js';
+describe('ClientCredentialsService', () => {
+    const configUrl = 'http://idp/.well-known/openid-configuration';
+    const credentials = {
+        audience: 'aud',
+        scope: 'scope',
+        clientId: 'cid',
+        clientSecret: 'secret',
+    };
+    let service;
+    let getOIDCConfigSpy;
+    let fetchTokenEndpointSpy;
+    beforeEach(() => {
+        service = new ClientCredentialsService(configUrl, undefined);
+        getOIDCConfigSpy = jest.spyOn(service, 'getOIDCConfig');
+        fetchTokenEndpointSpy = jest.spyOn(service, 'fetchTokenEndpoint');
+    });
+    it('returns access_token on success', async () => {
+        getOIDCConfigSpy.mockResolvedValue({
+            token_endpoint: 'http://idp/token',
+        });
+        fetchTokenEndpointSpy.mockResolvedValue({
+            ok: true,
+            json: jest
+                .fn()
+                .mockResolvedValue({ access_token: 'jwt' }),
+        });
+        const token = await service.fetchToken(credentials);
+        expect(token).toBe('jwt');
+    });
+    it('throws if OIDC config fetch fails', async () => {
+        getOIDCConfigSpy.mockRejectedValue(new Error('config fail'));
+        await expect(service.fetchToken(credentials)).rejects.toThrow('config fail');
+    });
+    it('throws if token endpoint fetch fails', async () => {
+        getOIDCConfigSpy.mockResolvedValue({
+            token_endpoint: 'http://idp/token',
+        });
+        fetchTokenEndpointSpy.mockRejectedValue(new Error('token fail'));
+        await expect(service.fetchToken(credentials)).rejects.toThrow('token fail');
+    });
+    it('throws if access_token missing', async () => {
+        getOIDCConfigSpy.mockResolvedValue({
+            token_endpoint: 'http://idp/token',
+        });
+        fetchTokenEndpointSpy.mockResolvedValue({
+            ok: true,
+            json: jest.fn().mockResolvedValue({}),
+        });
+        await expect(service.fetchToken(credentials)).rejects.toThrow('No access_token in token endpoint response');
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './auth-service.js';
+export * from './client-credentials-service.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,iCAAiC,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './auth-service.js';
+export * from './client-credentials-service.js';

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@canton-network/core-wallet-auth",
+  "version": "0.1.0",
+  "description": "Provides authentcation middleware and user management for the wallet kernel.",
+  "author": "Marc Juchli <marc.juchli@digitalasset.com>",
+  "license": "Apache-2.0",
+  "packageManager": "yarn@4.9.2",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "clean": "tsc -b --clean; rm -rf dist",
+    "test": "yarn node --experimental-vm-modules $(yarn bin jest) --passWithNoTests"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.0.0",
+    "@swc/core": "^1.11.31",
+    "@swc/jest": "^0.2.38",
+    "@types/jest": "^30.0.0",
+    "jest": "^30.0.0",
+    "ts-jest": "^29.4.0",
+    "ts-jest-resolver": "^2.0.1",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@canton-network/core-types": "^0.1.0"
+  },
+  "files": [
+    "dist/*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}