@bsv/sdk 1.8.6 → 1.8.8

package/src/auth/transports/SimplifiedFetchTransport.ts

@@ -44,27 +44,37 @@ export class SimplifiedFetchTransport implements Transport {
       return await new Promise((resolve, reject) => {
         void (async () => {
           try {
-            const responsePromise = this.fetchClient(`${this.baseUrl}/.well-known/auth`, {
-              method: 'POST',
-              headers: {
-                'Content-Type': 'application/json'
-              },
-              body: JSON.stringify(message)
-            })
+            const authUrl = `${this.baseUrl}/.well-known/auth`
+            const responsePromise = (async () => {
+              try {
+                return await this.fetchClient(authUrl, {
+                  method: 'POST',
+                  headers: {
+                    'Content-Type': 'application/json'
+                  },
+                  body: JSON.stringify(message)
+                })
+              } catch (error) {
+                throw this.createNetworkError(authUrl, error)
+              }
+            })()
 
             // For initialRequest message, mark connection as established and start pool.
             if (message.messageType !== 'initialRequest') {
               resolve()
             }
+
             const response = await responsePromise
-            // Handle the response if data is received and callback is set
-            if (response.ok && (this.onDataCallback != null)) {
+            if (!response.ok) {
+              const responseBodyArray = Array.from(new Uint8Array(await response.arrayBuffer()))
+              throw this.createUnauthenticatedResponseError(authUrl, response, responseBodyArray)
+            }
+
+            if (this.onDataCallback != null) {
               const responseMessage = await response.json()
               this.onDataCallback(responseMessage as AuthMessage)
-            } else {
-            // Server may be a non authenticated server
-              throw new Error('HTTP server failed to authenticate')
             }
+
             if (message.messageType === 'initialRequest') {
               resolve()
             }
@@ -118,22 +128,39 @@ export class SimplifiedFetchTransport implements Transport {
       }
 
       // Send the actual fetch request to the server
-      const response = await this.fetchClient(url, {
-        method: httpRequestWithAuthHeaders.method,
-        headers: httpRequestWithAuthHeaders.headers,
-        body: httpRequestWithAuthHeaders.body
-      })
+      let response: Response
+      try {
+        response = await this.fetchClient(url, {
+          method: httpRequestWithAuthHeaders.method,
+          headers: httpRequestWithAuthHeaders.headers,
+          body: httpRequestWithAuthHeaders.body
+        })
+      } catch (error) {
+        throw this.createNetworkError(url, error)
+      }
 
-      // Check for an acceptable status
-      if (response.status === 500 && (response.headers.get('x-bsv-auth-request-id') == null &&
-          response.headers.get('x-bsv-auth-requested-certificates') == null)) {
-        // Try parsing JSON error
-        const errorInfo = await response.json()
-        // Otherwise just throw whatever we got
-        throw new Error(`HTTP ${response.status} - ${JSON.stringify(errorInfo)}`)
+      const responseBodyBuffer = await response.arrayBuffer()
+      const responseBodyArray = Array.from(new Uint8Array(responseBodyBuffer))
+
+      const missingAuthHeaders = ['x-bsv-auth-version', 'x-bsv-auth-identity-key', 'x-bsv-auth-signature']
+        .filter(headerName => {
+          const headerValue = response.headers.get(headerName)
+          return headerValue == null || headerValue.trim().length === 0
+        })
+
+      if (missingAuthHeaders.length > 0) {
+        throw this.createUnauthenticatedResponseError(url, response, responseBodyArray, missingAuthHeaders)
       }
 
-      const parsedBody = await response.arrayBuffer()
+      const requestedCertificatesHeader = response.headers.get('x-bsv-auth-requested-certificates')
+      let requestedCertificates: RequestedCertificateSet | undefined
+      if (requestedCertificatesHeader != null) {
+        try {
+          requestedCertificates = JSON.parse(requestedCertificatesHeader) as RequestedCertificateSet
+        } catch (error) {
+          throw this.createMalformedHeaderError(url, 'x-bsv-auth-requested-certificates', requestedCertificatesHeader, error)
+        }
+      }
       const payloadWriter = new Utils.Writer()
       if (response.headers.get('x-bsv-auth-request-id') != null) {
         payloadWriter.write(Utils.toArray(response.headers.get('x-bsv-auth-request-id'), 'base64'))
@@ -171,12 +198,9 @@ export class SimplifiedFetchTransport implements Transport {
       }
 
       // Handle body
-      if (parsedBody != null) {
-        const bodyAsArray = Array.from(new Uint8Array(parsedBody))
-        payloadWriter.writeVarIntNum(bodyAsArray.length)
-        payloadWriter.write(bodyAsArray)
-      } else {
-        payloadWriter.writeVarIntNum(-1)
+      payloadWriter.writeVarIntNum(responseBodyArray.length)
+      if (responseBodyArray.length > 0) {
+        payloadWriter.write(responseBodyArray)
       }
 
       // Build the correct AuthMessage for the response
@@ -184,16 +208,16 @@ export class SimplifiedFetchTransport implements Transport {
         version: response.headers.get('x-bsv-auth-version'),
         messageType: response.headers.get('x-bsv-auth-message-type') === 'certificateRequest' ? 'certificateRequest' : 'general',
         identityKey: response.headers.get('x-bsv-auth-identity-key'),
-        nonce: response.headers.get('x-bsv-auth-nonce'),
-        yourNonce: response.headers.get('x-bsv-auth-your-nonce'),
-        requestedCertificates: JSON.parse(response.headers.get('x-bsv-auth-requested-certificates')) as RequestedCertificateSet,
+        nonce: response.headers.get('x-bsv-auth-nonce') ?? undefined,
+        yourNonce: response.headers.get('x-bsv-auth-your-nonce') ?? undefined,
+        requestedCertificates,
         payload: payloadWriter.toArray(),
         signature: Utils.toArray(response.headers.get('x-bsv-auth-signature'), 'hex')
       }
 
       // If the server didn't provide the correct authentication headers, throw an error
       if (responseMessage.version == null) {
-        throw new Error('HTTP server failed to authenticate')
+        throw this.createUnauthenticatedResponseError(url, response, responseBodyArray)
       }
 
       // Handle the response if data is received and callback is set
@@ -214,6 +238,132 @@ export class SimplifiedFetchTransport implements Transport {
     }
   }
 
+  private createNetworkError (url: string, originalError: unknown): Error {
+    const baseMessage = `Network error while sending authenticated request to ${url}`
+    if (originalError instanceof Error) {
+      const error = new Error(`${baseMessage}: ${originalError.message}`)
+      error.stack = originalError.stack
+      ;(error as any).cause = originalError
+      return error
+    }
+    return new Error(`${baseMessage}: ${String(originalError)}`)
+  }
+
+  private createUnauthenticatedResponseError (
+    url: string,
+    response: Response,
+    bodyBytes: number[],
+    missingHeaders: string[] = []
+  ): Error {
+    const statusText = (response.statusText ?? '').trim()
+    const statusDescription = statusText.length > 0
+      ? `${response.status} ${statusText}`
+      : `${response.status}`
+    const headerMessage = missingHeaders.length > 0
+      ? `missing headers: ${missingHeaders.join(', ')}`
+      : 'response lacked required BSV auth headers'
+    const bodyPreview = this.getBodyPreview(bodyBytes, response.headers.get('content-type'))
+    const parts = [`Received HTTP ${statusDescription} from ${url} without valid BSV authentication (${headerMessage})`]
+    if (bodyPreview != null) {
+      parts.push(`body preview: ${bodyPreview}`)
+    }
+
+    const error = new Error(parts.join(' - '))
+    ;(error as any).details = {
+      url,
+      status: response.status,
+      statusText: response.statusText,
+      missingHeaders,
+      bodyPreview
+    }
+    return error
+  }
+
+  private createMalformedHeaderError (
+    url: string,
+    headerName: string,
+    headerValue: string,
+    cause: unknown
+  ): Error {
+    const errorMessage = `Failed to parse ${headerName} returned by ${url}: ${headerValue}`
+    if (cause instanceof Error) {
+      const error = new Error(`${errorMessage}. ${cause.message}`)
+      error.stack = cause.stack
+      ;(error as any).cause = cause
+      return error
+    }
+    return new Error(`${errorMessage}. ${String(cause)}`)
+  }
+
+  private getBodyPreview (bodyBytes: number[], contentType: string | null): string | undefined {
+    if (bodyBytes.length === 0) {
+      return undefined
+    }
+
+    const maxBytesForPreview = 1024
+    const truncated = bodyBytes.length > maxBytesForPreview
+    const slice = truncated ? bodyBytes.slice(0, maxBytesForPreview) : bodyBytes
+    const isText = this.isTextualContent(contentType, slice)
+
+    let preview: string
+    if (isText) {
+      try {
+        preview = Utils.toUTF8(slice)
+      } catch {
+        preview = this.formatBinaryPreview(slice, truncated)
+      }
+    } else {
+      preview = this.formatBinaryPreview(slice, truncated)
+    }
+
+    if (preview.length > 512) {
+      preview = `${preview.slice(0, 512)}…`
+    }
+    if (truncated) {
+      preview = `${preview} (truncated)`
+    }
+    return preview
+  }
+
+  private isTextualContent (contentType: string | null, sample: number[]): boolean {
+    if (sample.length === 0) {
+      return false
+    }
+
+    if (contentType != null) {
+      const lowered = contentType.toLowerCase()
+      const textualTokens = [
+        'application/json',
+        'application/problem+json',
+        'application/xml',
+        'application/xhtml+xml',
+        'application/javascript',
+        'application/ecmascript',
+        'application/x-www-form-urlencoded',
+        'text/'
+      ]
+      if (textualTokens.some(token => lowered.includes(token)) || lowered.includes('charset=')) {
+        return true
+      }
+    }
+
+    const printableCount = sample.reduce((count, byte) => {
+      if (byte === 9 || byte === 10 || byte === 13) {
+        return count + 1
+      }
+      if (byte >= 32 && byte <= 126) {
+        return count + 1
+      }
+      return count
+    }, 0)
+    return (printableCount / sample.length) > 0.8
+  }
+
+  private formatBinaryPreview (bytes: number[], truncated: boolean): string {
+    const hex = bytes.map(byte => byte.toString(16).padStart(2, '0')).join('')
+    return `0x${hex}${truncated ? '…' : ''}`
+  }
+
   /**
    * Deserializes a request payload from a byte array into an HTTP request-like structure.
    *

package/src/auth/transports/__tests__/SimplifiedFetchTransport.test.ts

@@ -0,0 +1,126 @@
+import { jest } from '@jest/globals'
+import { SimplifiedFetchTransport } from '../SimplifiedFetchTransport.js'
+import * as Utils from '../../../primitives/utils.js'
+import { AuthMessage } from '../../types.js'
+
+function createGeneralPayload (path = '/resource', method = 'GET'): number[] {
+  const writer = new Utils.Writer()
+  const requestId = new Array(32).fill(1)
+  writer.write(requestId)
+
+  const methodBytes = Utils.toArray(method, 'utf8')
+  writer.writeVarIntNum(methodBytes.length)
+  writer.write(methodBytes)
+
+  const pathBytes = Utils.toArray(path, 'utf8')
+  writer.writeVarIntNum(pathBytes.length)
+  writer.write(pathBytes)
+
+  writer.writeVarIntNum(-1) // no query string
+  writer.writeVarIntNum(0) // no headers
+  writer.writeVarIntNum(-1) // no body
+
+  return writer.toArray()
+}
+
+function createGeneralMessage (overrides: Partial<AuthMessage> = {}): AuthMessage {
+  return {
+    version: '1.0',
+    messageType: 'general',
+    identityKey: 'client-key',
+    nonce: 'client-nonce',
+    yourNonce: 'server-nonce',
+    payload: createGeneralPayload(),
+    signature: new Array(64).fill(0),
+    ...overrides
+  }
+}
+
+afterEach(() => {
+  jest.restoreAllMocks()
+})
+
+describe('SimplifiedFetchTransport send', () => {
+  test('wraps network failures with context', async () => {
+    const fetchMock: jest.MockedFunction<typeof fetch> = jest.fn()
+    fetchMock.mockRejectedValue(new Error('network down'))
+    const transport = new SimplifiedFetchTransport('https://api.example.com', fetchMock as any)
+    await transport.onData(async () => {})
+    const message = createGeneralMessage()
+
+    let caught: any
+    await expect((async () => {
+      try {
+        await transport.send(message)
+      } catch (error) {
+        caught = error
+        throw error
+      }
+    })()).rejects.toThrow('Network error while sending authenticated request to https://api.example.com/resource: network down')
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(fetchMock.mock.calls[0][0]).toBe('https://api.example.com/resource')
+    expect(caught).toBeInstanceOf(Error)
+    expect(caught.cause).toBeInstanceOf(Error)
+    expect(caught.cause?.message).toBe('network down')
+  })
+
+  test('throws when server omits authentication headers', async () => {
+    const response = new Response('missing auth', {
+      status: 200,
+      headers: {
+        'Content-Type': 'text/plain'
+      }
+    })
+    const fetchMock: jest.MockedFunction<typeof fetch> = jest.fn()
+    fetchMock.mockResolvedValue(response)
+    const transport = new SimplifiedFetchTransport('https://api.example.com', fetchMock as any)
+    await transport.onData(async () => {})
+
+    const message = createGeneralMessage()
+
+    let thrown: any
+    await expect((async () => {
+      try {
+        await transport.send(message)
+      } catch (error) {
+        thrown = error
+        throw error
+      }
+    })()).rejects.toThrow('Received HTTP 200 from https://api.example.com/resource without valid BSV authentication (missing headers: x-bsv-auth-version, x-bsv-auth-identity-key, x-bsv-auth-signature)')
+
+    expect(thrown.details).toMatchObject({
+      url: 'https://api.example.com/resource',
+      status: 200,
+      missingHeaders: [
+        'x-bsv-auth-version',
+        'x-bsv-auth-identity-key',
+        'x-bsv-auth-signature'
+      ]
+    })
+    expect(thrown.details.bodyPreview).toContain('missing auth')
+  })
+
+  test('rejects malformed requested certificates header', async () => {
+    const fetchMock: jest.MockedFunction<typeof fetch> = jest.fn()
+    fetchMock.mockResolvedValue(new Response('', {
+      status: 200,
+      headers: {
+        'x-bsv-auth-version': '0.1',
+        'x-bsv-auth-identity-key': 'server-key',
+        'x-bsv-auth-signature': 'deadbeef',
+        'x-bsv-auth-message-type': 'general',
+        'x-bsv-auth-request-id': Utils.toBase64(new Array(32).fill(2)),
+        'x-bsv-auth-requested-certificates': 'not-json'
+      }
+    }))
+
+    const transport = new SimplifiedFetchTransport('https://api.example.com', fetchMock as any)
+    await transport.onData(async () => {})
+    const message = createGeneralMessage()
+
+    await expect(transport.send(message)).rejects.toThrow(
+      'Failed to parse x-bsv-auth-requested-certificates returned by https://api.example.com/resource: not-json'
+    )
+  })
+})

package/src/kvstore/GlobalKVStore.ts

@@ -138,6 +138,7 @@ export class GlobalKVStore {
     const tokenSetDescription = (options.tokenSetDescription != null && options.tokenSetDescription !== '') ? options.tokenSetDescription : `Create KVStore value for ${key}`
     const tokenUpdateDescription = (options.tokenUpdateDescription != null && options.tokenUpdateDescription !== '') ? options.tokenUpdateDescription : `Update KVStore value for ${key}`
     const tokenAmount = options.tokenAmount ?? this.config.tokenAmount
+    const tags = options.tags ?? []
 
     try {
       // Check for existing token to spend
@@ -146,13 +147,20 @@ export class GlobalKVStore {
 
       // Create PushDrop locking script
       const pushdrop = new PushDrop(this.wallet, this.config.originator)
+      const lockingScriptFields = [
+        Utils.toArray(JSON.stringify(protocolID), 'utf8'),
+        Utils.toArray(key, 'utf8'),
+        Utils.toArray(value, 'utf8'),
+        Utils.toArray(controller, 'hex')
+      ]
+
+      // Add tags as optional 5th field for backwards compatibility
+      if (tags.length > 0) {
+        lockingScriptFields.push(Utils.toArray(JSON.stringify(tags), 'utf8'))
+      }
+
       const lockingScript = await pushdrop.lock(
-        [
-          Utils.toArray(JSON.stringify(protocolID), 'utf8'),
-          Utils.toArray(key, 'utf8'),
-          Utils.toArray(value, 'utf8'),
-          Utils.toArray(controller, 'hex')
-        ],
+        lockingScriptFields,
         protocolID ?? this.config.protocolID as WalletProtocol,
         Utils.toUTF8(Utils.toArray(key, 'utf8')),
         'anyone',
@@ -409,7 +417,12 @@ export class GlobalKVStore {
         const output = tx.outputs[result.outputIndex]
         const decoded = PushDrop.decode(output.lockingScript)
 
-        if (decoded.fields.length !== 5) {
+        // Support backwards compatibility: old format without tags, new format with tags
+        const expectedFieldCount = Object.keys(kvProtocol).length
+        const hasTagsField = decoded.fields.length === expectedFieldCount
+        const isOldFormat = decoded.fields.length === expectedFieldCount - 1
+
+        if (!isOldFormat && !hasTagsField) {
           continue
         }
 
@@ -429,11 +442,23 @@ export class GlobalKVStore {
           continue
         }
 
+        // Extract tags if present (backwards compatible)
+        let tags: string[] | undefined
+        if (hasTagsField && decoded.fields[kvProtocol.tags] != null) {
+          try {
+            tags = JSON.parse(Utils.toUTF8(decoded.fields[kvProtocol.tags]))
+          } catch (e) {
+            // If tags parsing fails, continue without tags
+            tags = undefined
+          }
+        }
+
         const entry: KVStoreEntry = {
           key: Utils.toUTF8(decoded.fields[kvProtocol.key]),
           value: Utils.toUTF8(decoded.fields[kvProtocol.value]),
           controller: Utils.toHex(decoded.fields[kvProtocol.controller]),
-          protocolID: JSON.parse(Utils.toUTF8(decoded.fields[kvProtocol.protocolID]))
+          protocolID: JSON.parse(Utils.toUTF8(decoded.fields[kvProtocol.protocolID])),
+          tags
         }
 
         if (options.includeToken === true) {

package/src/kvstore/__tests/GlobalKVStore.test.ts

@@ -287,6 +287,46 @@ describe('GlobalKVStore', () => {
         })
       })
 
+      it('returns entry with tags when token includes tags field', async () => {
+        primeResolverWithOneOutput(mockResolver)
+
+        const originalDecode = (MockPushDrop as any).decode
+        ;(MockPushDrop as any).decode = jest.fn().mockReturnValue({
+          fields: [
+            Array.from(Buffer.from(JSON.stringify([1, 'kvstore']))), // protocolID
+            Array.from(Buffer.from(TEST_KEY)), // key
+            Array.from(Buffer.from(TEST_VALUE)), // value
+            Array.from(Buffer.from(TEST_CONTROLLER, 'hex')), // controller
+            // tags field as JSON string so Utils.toUTF8 returns it directly
+            '["alpha","beta"]',
+            Array.from(Buffer.from('signature')) // signature
+          ]
+        })
+
+        const result = await kvStore.get({ key: TEST_KEY })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(result).toHaveLength(1)
+        if (Array.isArray(result) && result.length > 0) {
+          expect(result[0].tags).toEqual(['alpha', 'beta'])
+        }
+
+        ;(MockPushDrop as any).decode = originalDecode
+      })
+
+      it('omits tags when token is in old-format (no tags field)', async () => {
+        primeResolverWithOneOutput(mockResolver)
+
+        // primePushDropDecodeToValidValue() already sets old-format (no tags)
+        const result = await kvStore.get({ key: TEST_KEY })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(result).toHaveLength(1)
+        if (Array.isArray(result) && result.length > 0) {
+          expect(result[0].tags).toBeUndefined()
+        }
+      })
+
       it('returns entry with history when history=true', async () => {
         primeResolverWithOneOutput(mockResolver)
         mockHistorian.buildHistory.mockResolvedValue(['oldValue', TEST_VALUE])
@@ -320,6 +360,67 @@ describe('GlobalKVStore', () => {
         })
       })
 
+      it('forwards tags-only queries to the resolver', async () => {
+        primeResolverEmpty(mockResolver)
+
+        const tags = ['group:music', 'env:prod']
+        const result = await kvStore.get({ tags })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(mockResolver.query).toHaveBeenCalledWith({
+          service: 'ls_kvstore',
+          query: expect.objectContaining({ tags })
+        })
+      })
+
+      it('forwards tagQueryMode "all" to the resolver (default)', async () => {
+        primeResolverEmpty(mockResolver)
+
+        const tags = ['music', 'rock']
+        const result = await kvStore.get({ tags, tagQueryMode: 'all' })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(mockResolver.query).toHaveBeenCalledWith({
+          service: 'ls_kvstore',
+          query: expect.objectContaining({ 
+            tags,
+            tagQueryMode: 'all'
+          })
+        })
+      })
+
+      it('forwards tagQueryMode "any" to the resolver', async () => {
+        primeResolverEmpty(mockResolver)
+
+        const tags = ['music', 'jazz']
+        const result = await kvStore.get({ tags, tagQueryMode: 'any' })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(mockResolver.query).toHaveBeenCalledWith({
+          service: 'ls_kvstore',
+          query: expect.objectContaining({ 
+            tags,
+            tagQueryMode: 'any'
+          })
+        })
+      })
+
+      it('defaults to tagQueryMode "all" when not specified', async () => {
+        primeResolverEmpty(mockResolver)
+
+        const tags = ['category:news']
+        const result = await kvStore.get({ tags })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(mockResolver.query).toHaveBeenCalledWith({
+          service: 'ls_kvstore',
+          query: expect.objectContaining({ tags })
+        })
+        // Verify tagQueryMode is not explicitly set (will default to 'all' on server side)
+        const call = (mockResolver.query as jest.Mock).mock.calls[0][0]
+        expect(call.query.tagQueryMode).toBeUndefined()
+      })
+
       it('includes token data when includeToken=true for key queries', async () => {
         primeResolverWithOneOutput(mockResolver)
 
@@ -644,6 +745,34 @@ describe('GlobalKVStore', () => {
         expect(mockBroadcaster.broadcast).toHaveBeenCalled()
       })
 
+      it('includes tags field in locking script when options.tags provided', async () => {
+        primeResolverEmpty(mockResolver)
+
+        // Override PushDrop to capture the instance used within set()
+        const originalImpl = (MockPushDrop as any).mockImplementation
+        const mockLockingScript = { toHex: () => 'mockLockingScriptHex' }
+        const localPushDrop = {
+          lock: jest.fn().mockResolvedValue(mockLockingScript),
+          unlock: jest.fn().mockReturnValue({
+            sign: jest.fn().mockResolvedValue({ toHex: () => 'mockUnlockingScript' })
+          })
+        }
+        ;(MockPushDrop as any).mockImplementation(() => localPushDrop as any)
+
+        const providedTags = ['primary', 'news']
+        await kvStore.set(TEST_KEY, TEST_VALUE, { tags: providedTags })
+
+        // Validate PushDrop.lock was called with 5 fields (protocolID, key, value, controller, tags)
+        expect(localPushDrop.lock).toHaveBeenCalled()
+        const lockArgs = (localPushDrop.lock as jest.Mock).mock.calls[0]
+        const fields = lockArgs[0]
+        expect(Array.isArray(fields)).toBe(true)
+        expect(fields.length).toBe(5)
+
+        // Restore original implementation
+        ;(MockPushDrop as any).mockImplementation = originalImpl
+      })
+
       it('updates existing token when one exists', async () => {
         // Mock the queryOverlay to return an entry with a token
         const mockQueryOverlay = jest.spyOn(kvStore as any, 'queryOverlay')

package/src/kvstore/kvStoreInterpreter.ts

@@ -10,7 +10,8 @@ export interface KVContext { key: string, protocolID: WalletProtocol }
 /**
  * KVStore interpreter used by Historian.
  *
- * Validates the KVStore PushDrop tokens: [protocolID, key, value, controller, signature].
+ * Validates the KVStore PushDrop tokens: [protocolID, key, value, controller, signature] (old format)
+ * or [protocolID, key, value, controller, tags, signature] (new format).
  * Filters outputs by the provided key in the interpreter context.
  * Produces the plaintext value for matching outputs; returns undefined otherwise.
  *
@@ -30,8 +31,12 @@ export const kvStoreInterpreter: InterpreterFunction<string, KVContext> = async
     // Decode the KVStore token
     const decoded = PushDrop.decode(output.lockingScript)
 
-    // Validate KVStore token format (must have 5 fields: [protocolID, key, value, controller, signature])
-    if (decoded.fields.length !== Object.keys(kvProtocol).length) return undefined
+    // Support backwards compatibility: old format without tags, new format with tags
+    const expectedFieldCount = Object.keys(kvProtocol).length
+    const hasTagsField = decoded.fields.length === expectedFieldCount
+    const isOldFormat = decoded.fields.length === expectedFieldCount - 1
+
+    if (!isOldFormat && !hasTagsField) return undefined
 
     // Only return values for the given key and protocolID
     const key = Utils.toUTF8(decoded.fields[kvProtocol.key])

package/src/kvstore/types.ts

@@ -41,6 +41,13 @@ export interface KVStoreQuery {
   key?: string
   controller?: PubKeyHex
   protocolID?: WalletProtocol
+  tags?: string[]
+  /**
+   * Controls tag matching behavior when tags are specified.
+   * - 'all': Requires all specified tags to be present (default)
+   * - 'any': Requires at least one of the specified tags to be present
+   */
+  tagQueryMode?: 'all' | 'any'
   limit?: number
   skip?: number
   sortOrder?: 'asc' | 'desc'
@@ -63,6 +70,7 @@ export interface KVStoreSetOptions {
   tokenSetDescription?: string
   tokenUpdateDescription?: string
   tokenAmount?: number
+  tags?: string[]
 }
 
 export interface KVStoreRemoveOptions {
@@ -78,6 +86,7 @@ export interface KVStoreEntry {
   value: string
   controller: PubKeyHex
   protocolID: WalletProtocol
+  tags?: string[]
   token?: KVStoreToken
   history?: string[]
 }
@@ -110,5 +119,6 @@ export const kvProtocol = {
   key: 1,
   value: 2,
   controller: 3,
-  signature: 4
+  tags: 4,
+  signature: 5 // Note: signature moves to position 5 when tags are present
 }