refactor: narrow DynamoDB search terms via isEncryptedScalarQuery guard

Add an `isEncryptedScalarQuery` type guard to `@cipherstash/protect` that
narrows a value to protect-ffi's `EncryptedScalarQuery` — a scalar query
term carrying no ciphertext and exactly one of `hm`/`bf`/`ob`.

Use it in protect-dynamodb's `SearchTermsOperation` in place of the
hand-rolled `k`/`c`/`hm` property checks, so the narrowing is centralised,
self-documenting, and tied to protect-ffi's exact query type.

No behaviour change.

Author: freshtonic

packages/protect-dynamodb/src/operations/search-terms.ts

@@ -1,5 +1,9 @@
 import { type Result, withResult } from '@byteslice/result'
-import type { ProtectClient, SearchTerm } from '@cipherstash/protect'
+import {
+  type ProtectClient,
+  type SearchTerm,
+  isEncryptedScalarQuery,
+} from '@cipherstash/protect'
 import { handleError } from '../helpers'
 import type { ProtectDynamoDBError } from '../types'
 import {
@@ -56,7 +60,7 @@ export class SearchTermsOperation extends DynamoDBOperation<string[]> {
           // DynamoDB lookups go through equality queries → the FFI returns an
           // EncryptedScalarQuery carrying `hm`. Anything else (scalar storage,
           // a `bf`/`ob` query, or a SteVec payload) is a misconfiguration.
-          if (term?.k !== 'ct' || !('hm' in term) || typeof term.hm !== 'string') {
+          if (!isEncryptedScalarQuery(term) || !('hm' in term)) {
             throw new Error('expected encrypted search term to have an HMAC')
           }
 

packages/protect/src/helpers/index.ts

@@ -1,6 +1,7 @@
 import type {
   Encrypted as CipherStashEncrypted,
   EncryptedQuery as CipherStashEncryptedQuery,
+  EncryptedScalarQuery,
   KeysetIdentifier as KeysetIdentifierFfi,
 } from '@cipherstash/protect-ffi'
 import type {
@@ -158,6 +159,42 @@ export function isEncryptedPayload(value: unknown): value is Encrypted {
   return false
 }
 
+/**
+ * Type guard narrowing a value to {@link EncryptedScalarQuery} — the scalar
+ * query term (`unique` / `match` / `ore` lookup) returned by `encryptQuery` /
+ * `encryptQueryBulk`. Unlike a storage payload it carries no ciphertext (`c`);
+ * it carries exactly one lookup term: `hm`, `bf`, or `ob`.
+ *
+ * Use this to discriminate a scalar query term from a storage payload
+ * (`EncryptedScalar`/`EncryptedSteVec`) or a `ste_vec_selector` query.
+ */
+export function isEncryptedScalarQuery(
+  value: unknown,
+): value is EncryptedScalarQuery {
+  if (value === null || typeof value !== 'object') return false
+
+  const obj = value as Record<string, unknown>
+
+  // `k: 'ct'` is the scalar discriminant; a query term never carries the
+  // ciphertext (`c`) that every storage payload has.
+  if (obj.k !== 'ct' || 'c' in obj) return false
+  if (
+    typeof obj.v !== 'number' ||
+    typeof obj.i !== 'object' ||
+    obj.i === null
+  ) {
+    return false
+  }
+
+  // Exactly one lookup term: `hm` (unique), `bf` (match), or `ob` (ore).
+  const lookupTerms = [
+    typeof obj.hm === 'string',
+    Array.isArray(obj.bf),
+    Array.isArray(obj.ob),
+  ].filter(Boolean)
+  return lookupTerms.length === 1
+}
+
 export {
   toJsonPath,
   buildNestedObject,