@solana/keychain-dfns 0.0.0 → 0.6.1

package/src/__tests__/dfns-signer.test.ts

@@ -0,0 +1,217 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@solana/keychain-core', async importOriginal => {
+    const mod = await importOriginal<typeof import('@solana/keychain-core')>();
+    return { ...mod, assertSignatureValid: vi.fn() };
+});
+
+import { DfnsSigner } from '../dfns-signer.js';
+import {
+    TEST_AUTH_TOKEN,
+    TEST_CRED_ID,
+    TEST_ED25519_PEM,
+    TEST_WALLET_ID,
+    createSignatureResponse,
+    createUserActionInitResponse,
+    createUserActionResponse,
+    createWalletResponse,
+} from './setup.js';
+
+global.fetch = vi.fn();
+const mockFetch = global.fetch as ReturnType<typeof vi.fn>;
+
+const defaultConfig = {
+    authToken: TEST_AUTH_TOKEN,
+    credId: TEST_CRED_ID,
+    privateKeyPem: TEST_ED25519_PEM,
+    walletId: TEST_WALLET_ID,
+};
+
+function mockWalletFetch(overrides?: Parameters<typeof createWalletResponse>[0]) {
+    mockFetch.mockResolvedValueOnce({
+        json: async () => createWalletResponse(overrides),
+        ok: true,
+    });
+}
+
+describe('DfnsSigner', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+
+    describe('create', () => {
+        it('creates a DfnsSigner with valid config', async () => {
+            mockWalletFetch();
+            const signer = await DfnsSigner.create(defaultConfig);
+            expect(signer).toBeDefined();
+            expect(signer.address).toBeDefined();
+        });
+
+        it('throws error for missing authToken', async () => {
+            await expect(DfnsSigner.create({ ...defaultConfig, authToken: '' })).rejects.toThrow(
+                'Missing required authToken field',
+            );
+        });
+
+        it('throws error for missing credId', async () => {
+            await expect(DfnsSigner.create({ ...defaultConfig, credId: '' })).rejects.toThrow(
+                'Missing required credId field',
+            );
+        });
+
+        it('throws error for missing privateKeyPem', async () => {
+            await expect(DfnsSigner.create({ ...defaultConfig, privateKeyPem: '' })).rejects.toThrow(
+                'Missing required privateKeyPem field',
+            );
+        });
+
+        it('throws error for missing walletId', async () => {
+            await expect(DfnsSigner.create({ ...defaultConfig, walletId: '' })).rejects.toThrow(
+                'Missing required walletId field',
+            );
+        });
+
+        it('throws error for inactive wallet', async () => {
+            mockWalletFetch({ status: 'Inactive' });
+            await expect(DfnsSigner.create(defaultConfig)).rejects.toThrow('not active');
+        });
+
+        it('throws error for non-EdDSA scheme', async () => {
+            mockWalletFetch({ scheme: 'ECDSA' });
+            await expect(DfnsSigner.create(defaultConfig)).rejects.toThrow('Unsupported key scheme');
+        });
+
+        it('throws error for API failure', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 401,
+            });
+            await expect(DfnsSigner.create(defaultConfig)).rejects.toThrow();
+        });
+
+        it('throws error for negative requestDelayMs', async () => {
+            await expect(DfnsSigner.create({ ...defaultConfig, requestDelayMs: -1 })).rejects.toThrow(
+                'requestDelayMs must not be negative',
+            );
+        });
+
+        it('warns for high requestDelayMs', async () => {
+            const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+            mockWalletFetch();
+            await DfnsSigner.create({ ...defaultConfig, requestDelayMs: 5000 });
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('requestDelayMs is greater than 3000ms'));
+            warnSpy.mockRestore();
+        });
+
+        it('throws HTTP_ERROR when fetch fails during create', async () => {
+            mockFetch.mockRejectedValueOnce(new Error('Network timeout'));
+            await expect(DfnsSigner.create(defaultConfig)).rejects.toMatchObject({
+                code: 'SIGNER_HTTP_ERROR',
+                message: expect.stringContaining('Dfns network request failed'),
+            });
+        });
+    });
+
+    describe('signMessages', () => {
+        it('throws HTTP_ERROR when fetch fails during signing', async () => {
+            mockWalletFetch();
+            const signer = await DfnsSigner.create(defaultConfig);
+
+            // The auth flow init request fails with network error
+            mockFetch.mockRejectedValueOnce(new Error('Network timeout'));
+
+            await expect(
+                signer.signMessages([{ content: new Uint8Array([1, 2, 3]), signatures: {} }]),
+            ).rejects.toMatchObject({
+                code: 'SIGNER_HTTP_ERROR',
+                message: expect.stringContaining('Dfns network request failed'),
+            });
+        });
+
+        it('signs a message successfully', async () => {
+            const rHex = '11'.repeat(32);
+            const sHex = '22'.repeat(32);
+
+            mockWalletFetch();
+
+            mockFetch.mockResolvedValueOnce({
+                json: async () => createUserActionInitResponse(),
+                ok: true,
+            });
+
+            mockFetch.mockResolvedValueOnce({
+                json: async () => createUserActionResponse(),
+                ok: true,
+            });
+
+            mockFetch.mockResolvedValueOnce({
+                json: async () => createSignatureResponse(rHex, sHex),
+                ok: true,
+            });
+
+            const signer = await DfnsSigner.create(defaultConfig);
+
+            const result = await signer.signMessages([{ content: new Uint8Array([1, 2, 3]), signatures: {} }]);
+
+            expect(result).toHaveLength(1);
+            expect(result[0]?.[signer.address]).toBeDefined();
+
+            const sig = result[0]![signer.address]!;
+            expect(sig.length).toBe(64);
+        });
+
+        it('left-pads short signature components', async () => {
+            // r is 31 bytes (short by 1), s is 32 bytes
+            const rHex = 'ff'.repeat(31);
+            const sHex = 'aa'.repeat(32);
+
+            mockWalletFetch();
+
+            mockFetch.mockResolvedValueOnce({
+                json: async () => createUserActionInitResponse(),
+                ok: true,
+            });
+
+            mockFetch.mockResolvedValueOnce({
+                json: async () => createUserActionResponse(),
+                ok: true,
+            });
+
+            mockFetch.mockResolvedValueOnce({
+                json: async () => createSignatureResponse(rHex, sHex),
+                ok: true,
+            });
+
+            const signer = await DfnsSigner.create(defaultConfig);
+
+            const result = await signer.signMessages([{ content: new Uint8Array([1, 2, 3]), signatures: {} }]);
+
+            const sig = result[0]![signer.address]!;
+            expect(sig.length).toBe(64);
+            // First byte should be 0x00 (left-pad), then 31 bytes of 0xff
+            expect(sig[0]).toBe(0x00);
+            expect(sig[1]).toBe(0xff);
+        });
+    });
+
+    describe('isAvailable', () => {
+        it('returns true when API responds', async () => {
+            mockWalletFetch();
+            // isAvailable doesn't need create(), but we need a signer instance
+            mockWalletFetch(); // for the isAvailable call
+            const signer = await DfnsSigner.create(defaultConfig);
+            expect(await signer.isAvailable()).toBe(true);
+        });
+
+        it('returns false when API fails', async () => {
+            mockWalletFetch(); // for create()
+            const signer = await DfnsSigner.create(defaultConfig);
+
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 500,
+            });
+            expect(await signer.isAvailable()).toBe(false);
+        });
+    });
+});

package/src/__tests__/setup.ts

@@ -0,0 +1,76 @@
+import type { SolanaSigner } from '@solana/keychain-core';
+import { SignerTestConfig, TestScenario } from '@solana/keychain-test-utils';
+import { createDfnsSigner } from '../dfns-signer.js';
+
+export const TEST_AUTH_TOKEN = 'test-auth-token';
+export const TEST_CRED_ID = 'test-cred-id';
+export const TEST_WALLET_ID = 'test-wallet-id';
+export const TEST_KEY_ID = 'test-key-id';
+
+// Ed25519 test key in PKCS#8 PEM format
+export const TEST_ED25519_PEM = `-----BEGIN PRIVATE KEY-----
+MC4CAQAwBQYDK2VwBCIEIJ+DYvh6SEqVTm50DFtMDoQikUmifl1yiWd+IiYyoHBD
+-----END PRIVATE KEY-----`;
+
+export const TEST_PUBKEY_HEX = '5da30b28c87836b0ee76ae7b07e3a2e3be1a4c12e48fce3aee18de0a13040b9a';
+
+export function createWalletResponse(overrides?: Partial<{ status: string; scheme: string; curve: string }>) {
+    return {
+        id: TEST_WALLET_ID,
+        network: 'Solana',
+        signingKey: {
+            id: TEST_KEY_ID,
+            curve: overrides?.curve ?? 'ed25519',
+            publicKey: TEST_PUBKEY_HEX,
+            scheme: overrides?.scheme ?? 'EdDSA',
+        },
+        status: overrides?.status ?? 'Active',
+    };
+}
+
+export function createUserActionInitResponse() {
+    return {
+        allowCredentials: {
+            key: [{ id: TEST_CRED_ID }],
+        },
+        challenge: 'test-challenge',
+        challengeIdentifier: 'test-challenge-id',
+    };
+}
+
+export function createUserActionResponse() {
+    return {
+        userAction: 'test-user-action-token',
+    };
+}
+
+export function createSignatureResponse(r: string, s: string) {
+    return {
+        id: 'sig-123',
+        signature: { r, s },
+        status: 'Signed',
+    };
+}
+
+const SIGNER_TYPE = 'dfns';
+const REQUIRED_ENV_VARS = ['DFNS_AUTH_TOKEN', 'DFNS_CRED_ID', 'DFNS_PRIVATE_KEY_PEM', 'DFNS_WALLET_ID'];
+
+const CONFIG: SignerTestConfig<SolanaSigner> = {
+    signerType: SIGNER_TYPE,
+    requiredEnvVars: REQUIRED_ENV_VARS,
+    createSigner: () =>
+        createDfnsSigner({
+            authToken: process.env.DFNS_AUTH_TOKEN!,
+            credId: process.env.DFNS_CRED_ID!,
+            privateKeyPem: process.env.DFNS_PRIVATE_KEY_PEM!,
+            walletId: process.env.DFNS_WALLET_ID!,
+            apiBaseUrl: process.env.DFNS_API_BASE_URL,
+        }),
+};
+
+export async function getConfig(scenarios: TestScenario[]): Promise<SignerTestConfig<SolanaSigner>> {
+    return {
+        ...CONFIG,
+        testScenarios: scenarios,
+    };
+}

package/src/auth.ts

@@ -0,0 +1,136 @@
+import * as crypto from 'node:crypto';
+
+import { base64UrlDecoder, SignerErrorCode, throwSignerError } from '@solana/keychain-core';
+
+import type { UserActionInitResponse, UserActionResponse } from './types.js';
+
+/**
+ * Perform the Dfns User Action Signing flow. For more details, see https://docs.dfns.co/api-reference/auth/signing-flows#asymetric-keys-signing-flow
+ *
+ * @returns The `userAction` token to include as `x-dfns-useraction` header.
+ */
+export async function signUserAction(
+    apiBaseUrl: string,
+    authToken: string,
+    credId: string,
+    privateKeyPem: string,
+    httpMethod: string,
+    httpPath: string,
+    body: string,
+): Promise<string> {
+    // Request a challenge
+    const initUrl = `${apiBaseUrl}/auth/action/init`;
+    let initResponse: Response;
+    try {
+        initResponse = await fetch(initUrl, {
+            body: JSON.stringify({
+                userActionHttpMethod: httpMethod,
+                userActionHttpPath: httpPath,
+                userActionPayload: body,
+                userActionServerKind: 'Api',
+            }),
+            headers: {
+                Authorization: `Bearer ${authToken}`,
+                'Content-Type': 'application/json',
+            },
+            method: 'POST',
+        });
+    } catch (error) {
+        throwSignerError(SignerErrorCode.HTTP_ERROR, {
+            cause: error,
+            message: 'Dfns network request failed',
+            url: initUrl,
+        });
+    }
+
+    if (!initResponse.ok) {
+        const errorText = await initResponse.text().catch(() => 'Failed to read error response');
+        throwSignerError(SignerErrorCode.REMOTE_API_ERROR, {
+            message: `Dfns auth/action/init failed: ${initResponse.status}`,
+            response: errorText,
+            status: initResponse.status,
+        });
+    }
+
+    let challenge: UserActionInitResponse;
+    try {
+        challenge = (await initResponse.json()) as UserActionInitResponse;
+    } catch (error) {
+        throwSignerError(SignerErrorCode.PARSING_ERROR, {
+            cause: error,
+            message: 'Failed to parse Dfns auth challenge response',
+        });
+    }
+
+    // Verify credential is allowed
+    const allowed = challenge.allowCredentials.key.some(c => c.id === credId);
+    if (!allowed) {
+        throwSignerError(SignerErrorCode.CONFIG_ERROR, {
+            message: `Credential ${credId} not in allowed credentials`,
+        });
+    }
+
+    // Sign the challenge
+    const clientData = new TextEncoder().encode(
+        JSON.stringify({
+            challenge: challenge.challenge,
+            type: 'key.get',
+        }),
+    );
+
+    const signature = crypto.sign(undefined, clientData, privateKeyPem);
+
+    const clientDataB64 = base64UrlDecoder(clientData);
+    const signatureB64 = base64UrlDecoder(new Uint8Array(signature));
+
+    // Submit the signed challenge
+    const actionUrl = `${apiBaseUrl}/auth/action`;
+    let signResponse: Response;
+    try {
+        signResponse = await fetch(actionUrl, {
+            body: JSON.stringify({
+                challengeIdentifier: challenge.challengeIdentifier,
+                firstFactor: {
+                    credentialAssertion: {
+                        clientData: clientDataB64,
+                        credId,
+                        signature: signatureB64,
+                    },
+                    kind: 'Key',
+                },
+            }),
+            headers: {
+                Authorization: `Bearer ${authToken}`,
+                'Content-Type': 'application/json',
+            },
+            method: 'POST',
+        });
+    } catch (error) {
+        throwSignerError(SignerErrorCode.HTTP_ERROR, {
+            cause: error,
+            message: 'Dfns network request failed',
+            url: actionUrl,
+        });
+    }
+
+    if (!signResponse.ok) {
+        const errorText = await signResponse.text().catch(() => 'Failed to read error response');
+        throwSignerError(SignerErrorCode.REMOTE_API_ERROR, {
+            message: `Dfns auth/action failed: ${signResponse.status}`,
+            response: errorText,
+            status: signResponse.status,
+        });
+    }
+
+    let actionResponse: UserActionResponse;
+    try {
+        actionResponse = (await signResponse.json()) as UserActionResponse;
+    } catch (error) {
+        throwSignerError(SignerErrorCode.PARSING_ERROR, {
+            cause: error,
+            message: 'Failed to parse Dfns auth action response',
+        });
+    }
+
+    return actionResponse.userAction;
+}