@solana/keychain 0.6.1 → 1.1.0

package/dist/resolve-address.d.ts

@@ -0,0 +1,26 @@
+import { type Address } from '@solana/addresses';
+import type { KeychainSignerConfig } from './types.js';
+/**
+ * Resolve the Solana address for a signer configuration without
+ * setting up the full signing pipeline.
+ *
+ * For backends that include the public key in their config (AWS KMS,
+ * CDP, GCP KMS, Turnkey, Vault), this returns the address directly
+ * with no network call. For backends that must fetch the public key
+ * from a remote API (Crossmint, Dfns, Fireblocks, Para, Privy),
+ * this initialises the signer and reads its address.
+ *
+ * @example
+ * ```typescript
+ * const address = await resolveAddress({
+ *     backend: 'vault',
+ *     vaultAddr: 'https://vault.example.com',
+ *     vaultToken: 'hvs.xxx',
+ *     keyName: 'my-key',
+ *     publicKey: '4Nd1m...',
+ * });
+ * // Returns '4Nd1m...' immediately — no network call
+ * ```
+ */
+export declare function resolveAddress(config: KeychainSignerConfig): Promise<Address>;
+//# sourceMappingURL=resolve-address.d.ts.map

package/dist/resolve-address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-address.d.ts","sourceRoot":"","sources":["../src/resolve-address.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAmB,MAAM,mBAAmB,CAAC;AAIlE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAgCnF"}

package/dist/resolve-address.js

@@ -0,0 +1,56 @@
+import { assertIsAddress } from '@solana/addresses';
+import { SignerErrorCode, throwSignerError } from '@solana/keychain-core';
+import { createKeychainSigner } from './create-keychain-signer.js';
+/**
+ * Resolve the Solana address for a signer configuration without
+ * setting up the full signing pipeline.
+ *
+ * For backends that include the public key in their config (AWS KMS,
+ * CDP, GCP KMS, Turnkey, Vault), this returns the address directly
+ * with no network call. For backends that must fetch the public key
+ * from a remote API (Crossmint, Dfns, Fireblocks, Para, Privy),
+ * this initialises the signer and reads its address.
+ *
+ * @example
+ * ```typescript
+ * const address = await resolveAddress({
+ *     backend: 'vault',
+ *     vaultAddr: 'https://vault.example.com',
+ *     vaultToken: 'hvs.xxx',
+ *     keyName: 'my-key',
+ *     publicKey: '4Nd1m...',
+ * });
+ * // Returns '4Nd1m...' immediately — no network call
+ * ```
+ */
+export async function resolveAddress(config) {
+    switch (config.backend) {
+        // Backends with publicKey in config — no network call needed
+        case 'aws-kms':
+        case 'gcp-kms':
+        case 'turnkey':
+        case 'vault':
+            assertIsAddress(config.publicKey);
+            return config.publicKey;
+        // CDP provides address directly in config
+        case 'cdp':
+            assertIsAddress(config.address);
+            return config.address;
+        // Backends that fetch the address from a remote API
+        case 'crossmint':
+        case 'dfns':
+        case 'fireblocks':
+        case 'para':
+        case 'privy': {
+            const signer = await createKeychainSigner(config);
+            return signer.address;
+        }
+        default: {
+            const _exhaustive = config;
+            return throwSignerError(SignerErrorCode.CONFIG_ERROR, {
+                message: `Unknown backend: ${String(_exhaustive.backend)}`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=resolve-address.js.map

package/dist/resolve-address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-address.js","sourceRoot":"","sources":["../src/resolve-address.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGnE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAA4B;IAC7D,QAAQ,MAAM,CAAC,OAAO,EAAE,CAAC;QACrB,6DAA6D;QAC7D,KAAK,SAAS,CAAC;QACf,KAAK,SAAS,CAAC;QACf,KAAK,SAAS,CAAC;QACf,KAAK,OAAO;YACR,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAClC,OAAO,MAAM,CAAC,SAAS,CAAC;QAE5B,0CAA0C;QAC1C,KAAK,KAAK;YACN,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAChC,OAAO,MAAM,CAAC,OAAO,CAAC;QAE1B,oDAAoD;QACpD,KAAK,WAAW,CAAC;QACjB,KAAK,MAAM,CAAC;QACZ,KAAK,YAAY,CAAC;QAClB,KAAK,MAAM,CAAC;QACZ,KAAK,OAAO,CAAC,CAAC,CAAC;YACX,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,MAAM,CAAC,CAAC;YAClD,OAAO,MAAM,CAAC,OAAO,CAAC;QAC1B,CAAC;QAED,OAAO,CAAC,CAAC,CAAC;YACN,MAAM,WAAW,GAAU,MAAM,CAAC;YAClC,OAAO,gBAAgB,CAAC,eAAe,CAAC,YAAY,EAAE;gBAClD,OAAO,EAAE,oBAAoB,MAAM,CAAE,WAAmC,CAAC,OAAO,CAAC,EAAE;aACtF,CAAC,CAAC;QACP,CAAC;IACL,CAAC;AACL,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+import type { AwsKmsSignerConfig } from '@solana/keychain-aws-kms';
+import type { CdpSignerConfig } from '@solana/keychain-cdp';
+import type { CrossmintSignerConfig } from '@solana/keychain-crossmint';
+import type { DfnsSignerConfig } from '@solana/keychain-dfns';
+import type { FireblocksSignerConfig } from '@solana/keychain-fireblocks';
+import type { GcpKmsSignerConfig } from '@solana/keychain-gcp-kms';
+import type { ParaSignerConfig } from '@solana/keychain-para';
+import type { PrivySignerConfig } from '@solana/keychain-privy';
+import type { TurnkeySignerConfig } from '@solana/keychain-turnkey';
+import type { VaultSignerConfig } from '@solana/keychain-vault';
+/**
+ * Discriminated union of all signer backend configurations.
+ * The `backend` field narrows the type to the correct config shape.
+ */
+export type KeychainSignerConfig = (AwsKmsSignerConfig & {
+    backend: 'aws-kms';
+}) | (CdpSignerConfig & {
+    backend: 'cdp';
+}) | (CrossmintSignerConfig & {
+    backend: 'crossmint';
+}) | (DfnsSignerConfig & {
+    backend: 'dfns';
+}) | (FireblocksSignerConfig & {
+    backend: 'fireblocks';
+}) | (GcpKmsSignerConfig & {
+    backend: 'gcp-kms';
+}) | (ParaSignerConfig & {
+    backend: 'para';
+}) | (PrivySignerConfig & {
+    backend: 'privy';
+}) | (TurnkeySignerConfig & {
+    backend: 'turnkey';
+}) | (VaultSignerConfig & {
+    backend: 'vault';
+});
+/** String literal union of all supported backend names, derived from {@link KeychainSignerConfig}. */
+export type BackendName = KeychainSignerConfig['backend'];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAC1B,CAAC,kBAAkB,GAAG;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC,GAC7C,CAAC,eAAe,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC,GACtC,CAAC,qBAAqB,GAAG;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC,GAClD,CAAC,gBAAgB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACxC,CAAC,sBAAsB,GAAG;IAAE,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,GACpD,CAAC,kBAAkB,GAAG;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC,GAC7C,CAAC,gBAAgB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACxC,CAAC,iBAAiB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,GAC1C,CAAC,mBAAmB,GAAG;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC,GAC9C,CAAC,iBAAiB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEjD,sGAAsG;AACtG,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -3,7 +3,7 @@
   "author": "Solana Foundation",
   "license": "MIT",
   "repository": "https://github.com/solana-foundation/solana-keychain",
-  "version": "0.6.1",
+  "version": "1.1.0",
   "description": "Unified Solana transaction signing across multiple backends",
   "keywords": [
     "solana",
@@ -36,17 +36,18 @@
     "src"
   ],
   "dependencies": {
-    "@solana/keychain-core": "0.6.1",
-    "@solana/keychain-cdp": "0.6.1",
-    "@solana/keychain-crossmint": "0.6.1",
-    "@solana/keychain-aws-kms": "0.6.1",
-    "@solana/keychain-dfns": "0.6.1",
-    "@solana/keychain-fireblocks": "0.6.1",
-    "@solana/keychain-para": "0.6.1",
-    "@solana/keychain-privy": "0.6.1",
-    "@solana/keychain-gcp-kms": "0.6.1",
-    "@solana/keychain-turnkey": "0.6.1",
-    "@solana/keychain-vault": "0.6.1"
+    "@solana/addresses": "^6.0.1",
+    "@solana/keychain-core": "1.1.0",
+    "@solana/keychain-cdp": "1.1.0",
+    "@solana/keychain-crossmint": "1.1.0",
+    "@solana/keychain-dfns": "1.1.0",
+    "@solana/keychain-aws-kms": "1.1.0",
+    "@solana/keychain-fireblocks": "1.1.0",
+    "@solana/keychain-para": "1.1.0",
+    "@solana/keychain-turnkey": "1.1.0",
+    "@solana/keychain-gcp-kms": "1.1.0",
+    "@solana/keychain-vault": "1.1.0",
+    "@solana/keychain-privy": "1.1.0"
   },
   "peerDependencies": {
     "@solana/addresses": ">=6.0.1",
@@ -62,7 +63,7 @@
   "scripts": {
     "build": "tsc --build",
     "clean": "rm -rf dist *.tsbuildinfo",
-    "test": "pnpm run typecheck",
+    "test": "vitest run && pnpm run typecheck",
     "typecheck": "tsc --noEmit",
     "test:treeshakability": "agadoo dist/index.js"
   }

package/src/__tests__/create-keychain-signer.test.ts

@@ -0,0 +1,154 @@
+import type { Address } from '@solana/addresses';
+import type { SolanaSigner } from '@solana/keychain-core';
+import { SignerErrorCode } from '@solana/keychain-core';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createKeychainSigner } from '../create-keychain-signer.js';
+import type { KeychainSignerConfig } from '../types.js';
+
+const TEST_ADDRESS = '11111111111111111111111111111111' as Address;
+
+function makeMockSigner(address: Address = TEST_ADDRESS): SolanaSigner {
+    return {
+        address,
+        isAvailable: vi.fn().mockResolvedValue(true),
+        signMessages: vi.fn().mockResolvedValue([]),
+        signTransactions: vi.fn().mockResolvedValue([]),
+    } as unknown as SolanaSigner;
+}
+
+// Mock all backend factories
+vi.mock('@solana/keychain-aws-kms', () => ({ createAwsKmsSigner: vi.fn() }));
+vi.mock('@solana/keychain-cdp', () => ({ createCdpSigner: vi.fn() }));
+vi.mock('@solana/keychain-crossmint', () => ({ createCrossmintSigner: vi.fn() }));
+vi.mock('@solana/keychain-dfns', () => ({ createDfnsSigner: vi.fn() }));
+vi.mock('@solana/keychain-fireblocks', () => ({ createFireblocksSigner: vi.fn() }));
+vi.mock('@solana/keychain-gcp-kms', () => ({ createGcpKmsSigner: vi.fn() }));
+vi.mock('@solana/keychain-para', () => ({ createParaSigner: vi.fn() }));
+vi.mock('@solana/keychain-privy', () => ({ createPrivySigner: vi.fn() }));
+vi.mock('@solana/keychain-turnkey', () => ({ createTurnkeySigner: vi.fn() }));
+vi.mock('@solana/keychain-vault', () => ({ createVaultSigner: vi.fn() }));
+
+// Table-driven test configs — one per backend
+const BACKEND_CONFIGS: Record<string, { config: KeychainSignerConfig; modulePath: string; factoryName: string }> = {
+    'aws-kms': {
+        config: { backend: 'aws-kms', keyId: 'key-1', publicKey: TEST_ADDRESS },
+        factoryName: 'createAwsKmsSigner',
+        modulePath: '@solana/keychain-aws-kms',
+    },
+    cdp: {
+        config: {
+            backend: 'cdp',
+            address: TEST_ADDRESS,
+            cdpApiKeyId: 'id',
+            cdpApiKeySecret: 's',
+            cdpWalletSecret: 'w',
+        },
+        factoryName: 'createCdpSigner',
+        modulePath: '@solana/keychain-cdp',
+    },
+    crossmint: {
+        config: { backend: 'crossmint', apiKey: 'key', walletLocator: 'loc' },
+        factoryName: 'createCrossmintSigner',
+        modulePath: '@solana/keychain-crossmint',
+    },
+    dfns: {
+        config: { backend: 'dfns', authToken: 'tok', credId: 'cred', privateKeyPem: 'pem', walletId: 'w' },
+        factoryName: 'createDfnsSigner',
+        modulePath: '@solana/keychain-dfns',
+    },
+    fireblocks: {
+        config: { backend: 'fireblocks', apiKey: 'key', privateKeyPem: 'pem', vaultAccountId: 'v' },
+        factoryName: 'createFireblocksSigner',
+        modulePath: '@solana/keychain-fireblocks',
+    },
+    'gcp-kms': {
+        config: { backend: 'gcp-kms', keyName: 'key', publicKey: TEST_ADDRESS },
+        factoryName: 'createGcpKmsSigner',
+        modulePath: '@solana/keychain-gcp-kms',
+    },
+    para: {
+        config: { backend: 'para', apiKey: 'key', walletId: 'w' },
+        factoryName: 'createParaSigner',
+        modulePath: '@solana/keychain-para',
+    },
+    privy: {
+        config: { backend: 'privy', appId: 'app', appSecret: 'secret', walletId: 'w' },
+        factoryName: 'createPrivySigner',
+        modulePath: '@solana/keychain-privy',
+    },
+    turnkey: {
+        config: {
+            backend: 'turnkey',
+            apiPrivateKey: 'pk',
+            apiPublicKey: 'pub',
+            organizationId: 'org',
+            privateKeyId: 'pkid',
+            publicKey: TEST_ADDRESS,
+        },
+        factoryName: 'createTurnkeySigner',
+        modulePath: '@solana/keychain-turnkey',
+    },
+    vault: {
+        config: {
+            backend: 'vault',
+            keyName: 'key',
+            publicKey: TEST_ADDRESS,
+            vaultAddr: 'https://v',
+            vaultToken: 'tok',
+        },
+        factoryName: 'createVaultSigner',
+        modulePath: '@solana/keychain-vault',
+    },
+};
+
+describe('createKeychainSigner', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    describe.each(Object.entries(BACKEND_CONFIGS))('%s', (_backend, { config, modulePath, factoryName }) => {
+        it('dispatches to the correct factory', async () => {
+            const mockSigner = makeMockSigner();
+            const mod = await import(modulePath);
+            const factory = mod[factoryName] as ReturnType<typeof vi.fn>;
+            factory.mockResolvedValue(mockSigner);
+
+            const result = await createKeychainSigner(config);
+
+            expect(result).toBe(mockSigner);
+            expect(factory).toHaveBeenCalledOnce();
+        });
+
+        it('passes config without the backend field', async () => {
+            const mockSigner = makeMockSigner();
+            const mod = await import(modulePath);
+            const factory = mod[factoryName] as ReturnType<typeof vi.fn>;
+            factory.mockResolvedValue(mockSigner);
+
+            await createKeychainSigner(config);
+
+            const passedConfig = factory.mock.calls[0]![0] as Record<string, unknown>;
+            expect(passedConfig).not.toHaveProperty('backend');
+        });
+
+        it('propagates factory errors', async () => {
+            const mod = await import(modulePath);
+            const factory = mod[factoryName] as ReturnType<typeof vi.fn>;
+            factory.mockRejectedValue(new Error('factory error'));
+
+            await expect(createKeychainSigner(config)).rejects.toThrow('factory error');
+        });
+    });
+
+    it('throws SignerError for unknown backend', async () => {
+        const badConfig = { backend: 'nonexistent' } as unknown as KeychainSignerConfig;
+
+        try {
+            await createKeychainSigner(badConfig);
+            expect.unreachable('should have thrown');
+        } catch (error) {
+            expect((error as { code: string }).code).toBe(SignerErrorCode.CONFIG_ERROR);
+        }
+    });
+});

package/src/__tests__/resolve-address.test.ts

@@ -0,0 +1,131 @@
+import type { Address } from '@solana/addresses';
+import type { SolanaSigner } from '@solana/keychain-core';
+import { SignerErrorCode } from '@solana/keychain-core';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { KeychainSignerConfig } from '../types.js';
+
+const TEST_ADDRESS = '11111111111111111111111111111111' as Address;
+
+function makeMockSigner(address: Address = TEST_ADDRESS): SolanaSigner {
+    return {
+        address,
+        isAvailable: vi.fn().mockResolvedValue(true),
+        signMessages: vi.fn().mockResolvedValue([]),
+        signTransactions: vi.fn().mockResolvedValue([]),
+    } as unknown as SolanaSigner;
+}
+
+// Mock createKeychainSigner so we don't pull in all backend deps
+vi.mock('../create-keychain-signer.js', () => ({
+    createKeychainSigner: vi.fn().mockResolvedValue(makeMockSigner()),
+}));
+
+// Must import after mock setup
+const { resolveAddress } = await import('../resolve-address.js');
+const { createKeychainSigner } = await import('../create-keychain-signer.js');
+
+describe('resolveAddress', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    describe('sync backends (publicKey in config)', () => {
+        it.each(['aws-kms', 'gcp-kms', 'turnkey', 'vault'] as const)('%s returns publicKey directly', async backend => {
+            const config = {
+                backend,
+                keyId: 'k',
+                keyName: 'k',
+                publicKey: TEST_ADDRESS,
+                vaultAddr: 'https://v',
+                vaultToken: 't',
+                apiPrivateKey: 'pk',
+                apiPublicKey: 'pub',
+                organizationId: 'org',
+                privateKeyId: 'pkid',
+            } as KeychainSignerConfig;
+
+            const address = await resolveAddress(config);
+
+            expect(address).toBe(TEST_ADDRESS);
+            expect(createKeychainSigner).not.toHaveBeenCalled();
+        });
+
+        it('throws for invalid publicKey', async () => {
+            const config = {
+                backend: 'vault' as const,
+                keyName: 'k',
+                publicKey: 'not-a-valid-address',
+                vaultAddr: 'https://v',
+                vaultToken: 't',
+            };
+
+            await expect(resolveAddress(config as KeychainSignerConfig)).rejects.toThrow();
+        });
+    });
+
+    describe('cdp (address in config)', () => {
+        it('returns address directly', async () => {
+            const config = {
+                backend: 'cdp' as const,
+                address: TEST_ADDRESS,
+                cdpApiKeyId: 'id',
+                cdpApiKeySecret: 's',
+                cdpWalletSecret: 'w',
+            };
+
+            const address = await resolveAddress(config as KeychainSignerConfig);
+
+            expect(address).toBe(TEST_ADDRESS);
+            expect(createKeychainSigner).not.toHaveBeenCalled();
+        });
+
+        it('throws for invalid address', async () => {
+            const config = {
+                backend: 'cdp' as const,
+                address: 'bad',
+                cdpApiKeyId: 'id',
+                cdpApiKeySecret: 's',
+                cdpWalletSecret: 'w',
+            };
+
+            await expect(resolveAddress(config as KeychainSignerConfig)).rejects.toThrow();
+        });
+    });
+
+    describe('async backends (fetch from API)', () => {
+        it.each(['crossmint', 'dfns', 'fireblocks', 'para', 'privy'] as const)(
+            '%s delegates to createKeychainSigner',
+            async backend => {
+                const config = {
+                    backend,
+                    apiKey: 'k',
+                    appId: 'a',
+                    appSecret: 's',
+                    authToken: 't',
+                    credId: 'c',
+                    privateKeyPem: 'p',
+                    vaultAccountId: 'v',
+                    walletId: 'w',
+                    walletLocator: 'l',
+                } as KeychainSignerConfig;
+
+                const address = await resolveAddress(config);
+
+                expect(address).toBe(TEST_ADDRESS);
+                expect(createKeychainSigner).toHaveBeenCalledWith(config);
+            },
+        );
+    });
+
+    it('throws SignerError for unknown backend', async () => {
+        const badConfig = { backend: 'nonexistent' } as unknown as KeychainSignerConfig;
+
+        try {
+            await resolveAddress(badConfig);
+            expect.unreachable('should have thrown');
+        } catch (error) {
+            expect((error as { code: string }).code).toBe(SignerErrorCode.CONFIG_ERROR);
+        }
+    });
+});

package/src/create-keychain-signer.ts

@@ -0,0 +1,65 @@
+import { createAwsKmsSigner } from '@solana/keychain-aws-kms';
+import { createCdpSigner } from '@solana/keychain-cdp';
+import type { SolanaSigner } from '@solana/keychain-core';
+import { SignerErrorCode, throwSignerError } from '@solana/keychain-core';
+import { createCrossmintSigner } from '@solana/keychain-crossmint';
+import { createDfnsSigner } from '@solana/keychain-dfns';
+import { createFireblocksSigner } from '@solana/keychain-fireblocks';
+import { createGcpKmsSigner } from '@solana/keychain-gcp-kms';
+import { createParaSigner } from '@solana/keychain-para';
+import { createPrivySigner } from '@solana/keychain-privy';
+import { createTurnkeySigner } from '@solana/keychain-turnkey';
+import { createVaultSigner } from '@solana/keychain-vault';
+
+import type { KeychainSignerConfig } from './types.js';
+
+function stripBackend<T extends { backend: string }>({ backend: _, ...rest }: T): Omit<T, 'backend'> {
+    return rest;
+}
+
+/**
+ * Create a {@link SolanaSigner} from a backend-tagged configuration.
+ *
+ * Dispatches to the correct `createXxxSigner()` factory based on
+ * the `backend` discriminant.
+ *
+ * @example
+ * ```typescript
+ * const signer = await createKeychainSigner({
+ *     backend: 'privy',
+ *     appId: '...',
+ *     appSecret: '...',
+ *     walletId: '...',
+ * });
+ * ```
+ */
+export async function createKeychainSigner(config: KeychainSignerConfig): Promise<SolanaSigner> {
+    switch (config.backend) {
+        case 'aws-kms':
+            return createAwsKmsSigner(stripBackend(config));
+        case 'cdp':
+            return await createCdpSigner(stripBackend(config));
+        case 'crossmint':
+            return await createCrossmintSigner(stripBackend(config));
+        case 'dfns':
+            return await createDfnsSigner(stripBackend(config));
+        case 'fireblocks':
+            return await createFireblocksSigner(stripBackend(config));
+        case 'gcp-kms':
+            return createGcpKmsSigner(stripBackend(config));
+        case 'para':
+            return await createParaSigner(stripBackend(config));
+        case 'privy':
+            return await createPrivySigner(stripBackend(config));
+        case 'turnkey':
+            return createTurnkeySigner(stripBackend(config));
+        case 'vault':
+            return createVaultSigner(stripBackend(config));
+        default: {
+            const _exhaustive: never = config;
+            return throwSignerError(SignerErrorCode.CONFIG_ERROR, {
+                message: `Unknown backend: ${String((_exhaustive as { backend: string }).backend)}`,
+            });
+        }
+    }
+}

package/src/index.ts

@@ -1,6 +1,23 @@
 // Core types and utilities (flat export)
 export * from '@solana/keychain-core';
 
+// Unified signer factory, address resolver, and config union
+export { createKeychainSigner } from './create-keychain-signer.js';
+export { resolveAddress } from './resolve-address.js';
+export type { BackendName, KeychainSignerConfig } from './types.js';
+
+// Individual config types (flat re-exports)
+export type { AwsKmsSignerConfig } from '@solana/keychain-aws-kms';
+export type { CdpSignerConfig } from '@solana/keychain-cdp';
+export type { CrossmintSignerConfig } from '@solana/keychain-crossmint';
+export type { DfnsSignerConfig } from '@solana/keychain-dfns';
+export type { FireblocksSignerConfig } from '@solana/keychain-fireblocks';
+export type { GcpKmsSignerConfig } from '@solana/keychain-gcp-kms';
+export type { ParaSignerConfig } from '@solana/keychain-para';
+export type { PrivySignerConfig } from '@solana/keychain-privy';
+export type { TurnkeySignerConfig } from '@solana/keychain-turnkey';
+export type { VaultSignerConfig } from '@solana/keychain-vault';
+
 // Signer implementations (namespaced to avoid conflicts)
 export * as awsKms from '@solana/keychain-aws-kms';
 export * as cdp from '@solana/keychain-cdp';

package/src/resolve-address.ts

@@ -0,0 +1,61 @@
+import { type Address, assertIsAddress } from '@solana/addresses';
+import { SignerErrorCode, throwSignerError } from '@solana/keychain-core';
+
+import { createKeychainSigner } from './create-keychain-signer.js';
+import type { KeychainSignerConfig } from './types.js';
+
+/**
+ * Resolve the Solana address for a signer configuration without
+ * setting up the full signing pipeline.
+ *
+ * For backends that include the public key in their config (AWS KMS,
+ * CDP, GCP KMS, Turnkey, Vault), this returns the address directly
+ * with no network call. For backends that must fetch the public key
+ * from a remote API (Crossmint, Dfns, Fireblocks, Para, Privy),
+ * this initialises the signer and reads its address.
+ *
+ * @example
+ * ```typescript
+ * const address = await resolveAddress({
+ *     backend: 'vault',
+ *     vaultAddr: 'https://vault.example.com',
+ *     vaultToken: 'hvs.xxx',
+ *     keyName: 'my-key',
+ *     publicKey: '4Nd1m...',
+ * });
+ * // Returns '4Nd1m...' immediately — no network call
+ * ```
+ */
+export async function resolveAddress(config: KeychainSignerConfig): Promise<Address> {
+    switch (config.backend) {
+        // Backends with publicKey in config — no network call needed
+        case 'aws-kms':
+        case 'gcp-kms':
+        case 'turnkey':
+        case 'vault':
+            assertIsAddress(config.publicKey);
+            return config.publicKey;
+
+        // CDP provides address directly in config
+        case 'cdp':
+            assertIsAddress(config.address);
+            return config.address;
+
+        // Backends that fetch the address from a remote API
+        case 'crossmint':
+        case 'dfns':
+        case 'fireblocks':
+        case 'para':
+        case 'privy': {
+            const signer = await createKeychainSigner(config);
+            return signer.address;
+        }
+
+        default: {
+            const _exhaustive: never = config;
+            return throwSignerError(SignerErrorCode.CONFIG_ERROR, {
+                message: `Unknown backend: ${String((_exhaustive as { backend: string }).backend)}`,
+            });
+        }
+    }
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+import type { AwsKmsSignerConfig } from '@solana/keychain-aws-kms';
+import type { CdpSignerConfig } from '@solana/keychain-cdp';
+import type { CrossmintSignerConfig } from '@solana/keychain-crossmint';
+import type { DfnsSignerConfig } from '@solana/keychain-dfns';
+import type { FireblocksSignerConfig } from '@solana/keychain-fireblocks';
+import type { GcpKmsSignerConfig } from '@solana/keychain-gcp-kms';
+import type { ParaSignerConfig } from '@solana/keychain-para';
+import type { PrivySignerConfig } from '@solana/keychain-privy';
+import type { TurnkeySignerConfig } from '@solana/keychain-turnkey';
+import type { VaultSignerConfig } from '@solana/keychain-vault';
+
+/**
+ * Discriminated union of all signer backend configurations.
+ * The `backend` field narrows the type to the correct config shape.
+ */
+export type KeychainSignerConfig =
+    | (AwsKmsSignerConfig & { backend: 'aws-kms' })
+    | (CdpSignerConfig & { backend: 'cdp' })
+    | (CrossmintSignerConfig & { backend: 'crossmint' })
+    | (DfnsSignerConfig & { backend: 'dfns' })
+    | (FireblocksSignerConfig & { backend: 'fireblocks' })
+    | (GcpKmsSignerConfig & { backend: 'gcp-kms' })
+    | (ParaSignerConfig & { backend: 'para' })
+    | (PrivySignerConfig & { backend: 'privy' })
+    | (TurnkeySignerConfig & { backend: 'turnkey' })
+    | (VaultSignerConfig & { backend: 'vault' });
+
+/** String literal union of all supported backend names, derived from {@link KeychainSignerConfig}. */
+export type BackendName = KeychainSignerConfig['backend'];