feat: support external signers for authenticated clients initialization

Signed-off-by: DaevMithran <daevmithran1999@gmail.com>

Author: DaevMithran

packages/http-signature-utils/src/index.ts

@@ -6,6 +6,10 @@ export {
   loadOrGenerateKey,
   loadBase64Key
 } from './utils/key'
-export { createSignatureHeaders, type RequestLike } from './utils/signatures'
+export {
+  createSignatureHeaders,
+  type RequestLike,
+  type Signer
+} from './utils/signatures'
 export { validateSignatureHeaders, validateSignature } from './utils/validation'
 export { generateTestKeys, TestKeys } from './test-utils/keys'

packages/http-signature-utils/src/utils/headers.ts

@@ -26,8 +26,7 @@ const createContentHeaders = (body: string): ContentHeaders => {
 
 export const createHeaders = async ({
   request,
-  privateKey,
-  keyId
+  ...signOptions
 }: SignOptions): Promise<Headers> => {
   const contentHeaders =
     request.body && createContentHeaders(request.body as string)
@@ -38,8 +37,7 @@ export const createHeaders = async ({
 
   const signatureHeaders = await createSignatureHeaders({
     request,
-    privateKey,
-    keyId
+    ...signOptions
   })
 
   return {

packages/http-signature-utils/src/utils/signatures.test.ts

@@ -1,5 +1,6 @@
 import { generateTestKeys, TestKeys } from '../test-utils/keys'
 import { createSignatureHeaders, RequestLike } from './signatures'
+import { sign } from 'crypto'
 
 describe('Signature Generation', (): void => {
   let testKeys: TestKeys
@@ -32,4 +33,30 @@ describe('Signature Generation', (): void => {
     expect(signatureParameters).toContain('keyid')
     expect(signatureParameters).toContain('created')
   })
+
+  test('uses a custom signer when provided', async (): Promise<void> => {
+    const request: RequestLike = {
+      headers: {},
+      method: 'GET',
+      url: 'http://example.com/test'
+    }
+
+    const signer = {
+      sign: jest.fn((data: Uint8Array): Uint8Array =>
+        sign(null, Buffer.from(data), testKeys.privateKey)
+      )
+    }
+
+    const signatureHeaders = await createSignatureHeaders({
+      request,
+      signer,
+      keyId: testKeys.publicKey.kid
+    })
+
+    expect(signer.sign).toHaveBeenCalledTimes(1)
+    expect(signatureHeaders.Signature).toBeDefined()
+    expect(signatureHeaders['Signature-Input']).toContain(
+      `keyid="${testKeys.publicKey.kid}"`
+    )
+  })
 })

packages/http-signature-utils/src/utils/signatures.ts

@@ -1,26 +1,56 @@
 import { type KeyLike } from 'crypto'
-import { httpbis, createSigner, Request } from 'http-message-signatures'
+import {
+  httpbis,
+  createSigner,
+  Request,
+  type SigningKey
+} from 'http-message-signatures'
 
 export interface RequestLike extends Request {
   body?: string
 }
 
-export interface SignOptions {
+export interface Signer {
+  sign(data: Uint8Array): Uint8Array | Promise<Uint8Array>
+}
+
+interface BaseSignOptions {
   request: RequestLike
-  privateKey: KeyLike
   keyId: string
 }
 
+export interface PrivateKeySignOptions extends BaseSignOptions {
+  privateKey: KeyLike
+}
+
+export interface SignerSignOptions extends BaseSignOptions {
+  signer: Signer
+}
+
+export type SignOptions = PrivateKeySignOptions | SignerSignOptions
+
 export interface SignatureHeaders {
   Signature: string
   'Signature-Input': string
 }
 
-export const createSignatureHeaders = async ({
-  request,
-  privateKey,
-  keyId
-}: SignOptions): Promise<SignatureHeaders> => {
+const createSigningKey = (options: SignOptions): SigningKey => {
+  if ('signer' in options) {
+    return {
+      id: options.keyId,
+      alg: 'ed25519',
+      sign: async (data: Buffer): Promise<Buffer> =>
+        Buffer.from(await options.signer.sign(data))
+    }
+  }
+
+  return createSigner(options.privateKey, 'ed25519', options.keyId)
+}
+
+export const createSignatureHeaders = async (
+  options: SignOptions
+): Promise<SignatureHeaders> => {
+  const { request } = options
   const components = ['@method', '@target-uri']
   if (request.headers['Authorization'] || request.headers['authorization']) {
     components.push('authorization')
@@ -29,7 +59,7 @@ export const createSignatureHeaders = async ({
     components.push('content-digest', 'content-length', 'content-type')
   }
 
-  const signingKey = createSigner(privateKey, 'ed25519', keyId)
+  const signingKey = createSigningKey(options)
 
   const { headers } = await httpbis.signMessage(
     {

packages/open-payments/README.md

@@ -61,7 +61,7 @@ const incomingPayment = await client.walletAddress.get({
 
 ### `AuthenticatedClient`
 
-An `AuthenticatedClient` provides all of the methods that `UnauthenticatedClient` does, as well as the rest of the Open Payment APIs (both the authorizaton and resource specs). Each request requiring authentication will be signed (using [HTTP Message Signatures](https://github.com/interledger/open-payments/tree/main/packages/http-signature-utils)) with the given private key.
+An `AuthenticatedClient` provides all of the methods that `UnauthenticatedClient` does, as well as the rest of the Open Payment APIs (both the authorizaton and resource specs). Each request requiring authentication will be signed (using [HTTP Message Signatures](https://github.com/interledger/open-payments/tree/main/packages/http-signature-utils)) with the given private key or signer.
 
 ```ts
 import { createAuthenticatedClient } from '@interledger/open-payments'
@@ -81,6 +81,22 @@ In order to create the client, three properties need to be provided: `keyId`, th
 | `privateKey`       | The private EdDSA-Ed25519 key (or the relative or absolute path to the key) bound to the wallet address, and used to sign the authenticated requests with. As mentioned above, a public JWK document signed with this key MUST be available at the `{walletAddressUrl}/jwks.json` url.                                                                                                                |
 | `keyId`            | The key identifier of the given private key and the corresponding public JWK document.                                                                                                                                                                                                                                                                                                                |
 
+For deployments where the private key is managed by a KMS, HSM, Secure Enclave, or another non-extractable key store, provide a signer instead of `privateKey`:
+
+```ts
+import { createAuthenticatedClient } from '@interledger/open-payments'
+
+const client = await createAuthenticatedClient({
+  keyId: KEY_ID,
+  signer: {
+    async sign(data: Uint8Array): Promise<Uint8Array> {
+      return kms.sign(data)
+    }
+  },
+  walletAddressUrl: WALLET_ADDRESS_URL
+})
+```
+
 > **Note**
 >
 > To simplify EdDSA-Ed25519 key provisioning and JWK generation, you can use methods from the [`@interledger/http-signature-utils`](https://github.com/interledger/open-payments/tree/main/packages/http-signature-utils) package.

packages/open-payments/src/client/index.test.ts

@@ -74,6 +74,19 @@ describe('Client', (): void => {
       ).resolves.toBeDefined()
     })
 
+    test('properly creates the client if a signer is passed', async (): Promise<void> => {
+      await expect(
+        createAuthenticatedClient({
+          logger: silentLogger,
+          keyId: 'keyid-1',
+          walletAddressUrl: 'http://localhost:1000/.well-known/pay',
+          signer: {
+            sign: jest.fn((data: Uint8Array): Uint8Array => data)
+          }
+        })
+      ).resolves.toBeDefined()
+    })
+
     test('throws error if could not load private key as Buffer', async (): Promise<void> => {
       expect.assertions(2)
       try {
@@ -134,10 +147,36 @@ describe('Client', (): void => {
             'Invalid arguments when creating authenticated client.'
           )
           expect(error.description).toBe(
-            'Both `authenticatedRequestInterceptor` and `privateKey`/`keyId` were provided. Please use only one of these options.'
+            'Exactly one of `authenticatedRequestInterceptor`, `privateKey`/`keyId`, or `signer`/`keyId` must be provided.'
           )
         }
       }
     )
+
+    test('throws an error if both privateKey and signer are provided', async (): Promise<void> => {
+      expect.assertions(2)
+      try {
+        const keypair = generateKeyPairSync('ed25519')
+
+        // @ts-expect-error Invalid args
+        await createAuthenticatedClient({
+          logger: silentLogger,
+          keyId: 'keyid-1',
+          walletAddressUrl: 'http://localhost:1000/.well-known/pay',
+          privateKey: keypair.privateKey,
+          signer: {
+            sign: jest.fn((data: Uint8Array): Uint8Array => data)
+          }
+        })
+      } catch (error) {
+        assert.ok(error instanceof OpenPaymentsClientError)
+        expect(error.message).toBe(
+          'Invalid arguments when creating authenticated client.'
+        )
+        expect(error.description).toBe(
+          'Exactly one of `authenticatedRequestInterceptor`, `privateKey`/`keyId`, or `signer`/`keyId` must be provided.'
+        )
+      }
+    })
   })
 })

packages/open-payments/src/client/index.ts

@@ -1,4 +1,4 @@
-import { loadKey } from '@interledger/http-signature-utils'
+import { loadKey, type Signer } from '@interledger/http-signature-utils'
 import fs from 'fs'
 import { OpenAPI } from '@interledger/openapi'
 import path from 'path'
@@ -167,6 +167,7 @@ const createAuthenticatedClientDeps = async ({
   ...args
 }:
   | CreateAuthenticatedClientArgs
+  | CreateAuthenticatedClientWithSignerArgs
   | CreateAuthenticatedClientWithReqInterceptorArgs): Promise<AuthenticatedClientDeps> => {
   const logger =
     args.logger ??
@@ -186,6 +187,16 @@ const createAuthenticatedClientDeps = async ({
         authenticatedRequestInterceptor: args.authenticatedRequestInterceptor
       }
     })
+  } else if ('signer' in args) {
+    httpClient = await createHttpClient({
+      logger,
+      requestTimeoutMs:
+        args.requestTimeoutMs ?? config.DEFAULT_REQUEST_TIMEOUT_MS,
+      requestSigningArgs: {
+        signer: args.signer,
+        keyId: args.keyId
+      }
+    })
   } else {
     let privateKey: KeyObject
     try {
@@ -295,6 +306,13 @@ interface PrivateKeyConfig {
   keyId: string
 }
 
+interface SignerConfig {
+  /** The external signer with which requests will be signed */
+  signer: Signer
+  /** The key identifier referring to the signer */
+  keyId: string
+}
+
 interface InterceptorConfig {
   /** The custom authenticated request interceptor to use. */
   authenticatedRequestInterceptor: InterceptorFn
@@ -303,6 +321,9 @@ interface InterceptorConfig {
 export type CreateAuthenticatedClientArgs = BaseAuthenticatedClientArgs &
   PrivateKeyConfig
 
+export type CreateAuthenticatedClientWithSignerArgs =
+  BaseAuthenticatedClientArgs & SignerConfig
+
 export type CreateAuthenticatedClientWithReqInterceptorArgs =
   BaseAuthenticatedClientArgs & InterceptorConfig
 
@@ -322,6 +343,13 @@ export interface AuthenticatedClient
 export async function createAuthenticatedClient(
   args: CreateAuthenticatedClientArgs
 ): Promise<AuthenticatedClient>
+/**
+ * Creates an Open Payments client that signs authenticated requests with an external signer.
+ * This is useful for KMS, HSM, Secure Enclave, or other non-extractable key deployments.
+ */
+export async function createAuthenticatedClient(
+  args: CreateAuthenticatedClientWithSignerArgs
+): Promise<AuthenticatedClient>
 /**
  * @experimental The `authenticatedRequestInterceptor` feature is currently experimental and might be removed
  * in upcoming versions. Use at your own risk! It offers the capability to add a custom method for
@@ -335,17 +363,27 @@ export async function createAuthenticatedClient(
 export async function createAuthenticatedClient(
   args:
     | CreateAuthenticatedClientArgs
+    | CreateAuthenticatedClientWithSignerArgs
     | CreateAuthenticatedClientWithReqInterceptorArgs
 ): Promise<AuthenticatedClient> {
+  const authConfigCount = [
+    'authenticatedRequestInterceptor' in args,
+    'privateKey' in args,
+    'signer' in args
+  ].filter(Boolean).length
+  const hasKeyId = 'keyId' in args && !!args.keyId
+  const needsKeyId = 'privateKey' in args || 'signer' in args
+
   if (
-    'authenticatedRequestInterceptor' in args &&
-    ('privateKey' in args || 'keyId' in args)
+    authConfigCount !== 1 ||
+    (needsKeyId && !hasKeyId) ||
+    ('authenticatedRequestInterceptor' in args && 'keyId' in args)
   ) {
     throw new OpenPaymentsClientError(
       'Invalid arguments when creating authenticated client.',
       {
         description:
-          'Both `authenticatedRequestInterceptor` and `privateKey`/`keyId` were provided. Please use only one of these options.'
+          'Exactly one of `authenticatedRequestInterceptor`, `privateKey`/`keyId`, or `signer`/`keyId` must be provided.'
       }
     )
   }

packages/open-payments/src/client/requests.test.ts

@@ -8,7 +8,7 @@ import {
   requestShouldBeAuthorized,
   signRequest
 } from './requests'
-import { generateKeyPairSync } from 'crypto'
+import { generateKeyPairSync, sign } from 'crypto'
 import nock from 'nock'
 import {
   createTestDeps,
@@ -827,6 +827,33 @@ describe('requests', (): void => {
       expect(signedRequest.headers.get('Content-Length')).toBeNull()
     })
 
+    test('sets signature headers with signer', async () => {
+      const request = new Request('https://localhost:1000/', {
+        method: 'POST'
+      })
+      const signer = {
+        sign: jest.fn((data: Uint8Array): Uint8Array =>
+          sign(null, Buffer.from(data), privateKey)
+        )
+      }
+
+      const signedRequest = await signRequest(request, {
+        keyId,
+        signer
+      })
+
+      expect(signer.sign).toHaveBeenCalledTimes(1)
+      expect(signedRequest.headers.get('Signature')).toMatch(
+        HTTP_SIGNATURE_REGEX
+      )
+      expect(signedRequest.headers.get('Signature-Input')).toMatch(
+        getSignatureInputRegex([], keyId)
+      )
+      expect(signedRequest.headers.get('Content-Digest')).toBeNull()
+      expect(signedRequest.headers.get('Content-Type')).toBeNull()
+      expect(signedRequest.headers.get('Content-Length')).toBeNull()
+    })
+
     test('sets signature headers with request body', async () => {
       const body = {
         foo: 'bar'