@cipherstash/stack 0.18.0 → 1.0.0-rc.0

package/dist/chunk-7333ZC6L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/match-defaults.ts"],"sourcesContent":["import type { MatchIndexOpts } from './index'\n\n/**\n * Fully-resolved match-index options: every field present and non-`undefined`.\n *\n * `MatchIndexOpts` (the user-facing tuning input) has all fields optional —\n * each is `.default(...).optional()` in the zod schema, so its inferred type is\n * `T | undefined`. This type pins the BUILT/resolved shape explicitly via\n * `NonNullable<...>`, which states the non-null intent directly and is robust\n * regardless of `Required<>`'s subtle, `exactOptionalPropertyTypes`-dependent\n * stripping semantics.\n */\nexport type BuiltMatchIndexOpts = {\n  tokenizer: NonNullable<MatchIndexOpts['tokenizer']>\n  token_filters: NonNullable<MatchIndexOpts['token_filters']>\n  k: NonNullable<MatchIndexOpts['k']>\n  m: NonNullable<MatchIndexOpts['m']>\n  include_original: NonNullable<MatchIndexOpts['include_original']>\n}\n\n/**\n * Default match-index parameters — the single source of truth shared by the\n * v2 `freeTextSearch()` builder and the v3 domain builders.\n *\n * `include_original: true` is the v2 builder's historical default rather than\n * the zod-schema default of `false`. It is INERT: protect-ffi accepts the flag\n * and ignores it (measured across 0.24 and 0.29, EQL v2 and v3 — the emitted\n * bloom is trigram-only either way). It is kept here only so the v2 emitted\n * config does not move. The v3 domain builders override it to `false`, the\n * value a substring-search domain wants if ffi ever starts honouring it.\n *\n * In particular it does NOT let a value shorter than the tokenizer's\n * `token_length` be matched: such a value blooms to nothing under either\n * setting, which is exactly the fail-open {@link matchNeedleError} guards.\n *\n * This is a FACTORY (not a shared `const`) so every caller gets fresh, unaliased\n * nested objects (`tokenizer`, `token_filters` and the `{ kind: 'downcase' }`\n * inside it). A shared const would be shallow-copied by `{ ...DEFAULT }`, leaving\n * those nested objects aliased across every column — a caller mutating one built\n * config could then corrupt the defaults used by later columns.\n */\nexport function defaultMatchOpts(): BuiltMatchIndexOpts {\n  return {\n    tokenizer: { kind: 'ngram', token_length: 3 },\n    token_filters: [{ kind: 'downcase' }],\n    k: 6,\n    m: 2048,\n    include_original: true,\n  }\n}\n\n/**\n * Deep-clone a built match block (`tokenizer` and `token_filters` are its only\n * nested values) so no emitted config or stored builder state ever aliases\n * another's nested objects — a caller mutating one cannot corrupt the other.\n */\nexport function cloneMatchOpts(opts: BuiltMatchIndexOpts): BuiltMatchIndexOpts {\n  return {\n    ...opts,\n    tokenizer: { ...opts.tokenizer },\n    token_filters: opts.token_filters.map((f) => ({ ...f })),\n  }\n}\n\n/**\n * Resolve user-supplied `freeTextSearch(opts)` input into a fully-built match\n * block: each provided key replaces its default, omitted keys keep the default\n * (`opts?.x ?? default.x`). The single source of truth for that five-field merge\n * shared by the v2 `freeTextSearch()` builder and the v3 domain builders.\n *\n * The result is deep-cloned ({@link cloneMatchOpts}) so a caller mutating their\n * own `opts` object (or its nested `tokenizer`/`token_filters`) after this call\n * can never leak into the stored builder state or the emitted config — clone-on-\n * write for both builders, not just v3.\n */\nexport function resolveMatchOpts(opts?: MatchIndexOpts): BuiltMatchIndexOpts {\n  const defaults = defaultMatchOpts()\n  return cloneMatchOpts({\n    tokenizer: opts?.tokenizer ?? defaults.tokenizer,\n    token_filters: opts?.token_filters ?? defaults.token_filters,\n    k: opts?.k ?? defaults.k,\n    m: opts?.m ?? defaults.m,\n    include_original: opts?.include_original ?? defaults.include_original,\n  })\n}\n\n/**\n * The shortest needle a match index can answer, or `undefined` when its\n * tokenizer imposes no floor (`standard` splits on word boundaries, so any\n * non-empty needle yields at least one token).\n *\n * Accepts the loose {@link MatchIndexOpts} because a `ColumnSchema`'s built\n * `indexes.match` is typed from the zod schema, where `tokenizer` is optional.\n * An absent tokenizer resolves to the same default the schema itself applies\n * (`ngram`, `token_length: 3`) rather than skipping the floor — skipping would\n * reintroduce the fail-open this guard exists to close.\n */\nexport function matchNeedleMinLength(opts: MatchIndexOpts): number | undefined {\n  const tokenizer = opts.tokenizer ?? defaultMatchOpts().tokenizer\n  return tokenizer.kind === 'ngram' ? tokenizer.token_length : undefined\n}\n\n/**\n * Why a needle cannot be answered by this match index, or `undefined` when it\n * can. Callers throw their own error type with this as the reason.\n *\n * A needle that tokenizes to NOTHING has an empty bloom filter, and\n * `stored_bf @> '{}'` is true for every row (\"contains nothing, contained by\n * everything\"). Such a query is unanswerable rather than merely unmatched, so\n * it must fail loudly instead of silently returning the whole table. Two ways\n * to tokenize to nothing:\n *\n *  - the empty needle, under ANY tokenizer;\n *  - a needle shorter than the ngram tokenizer's `token_length`.\n *\n * The ngram floor counts Unicode CODEPOINTS, because that is what the tokenizer\n * counts. `needle.length` would count UTF-16 code units and wave through an\n * astral-plane needle: `'👍👍'` is 4 code units but only 2 codepoints, yields no\n * trigram, and (measured live) matched every row. Graphemes are the wrong unit\n * in the other direction — NFD `'éé'` is 4 codepoints but 2 grapheme clusters,\n * and does yield trigrams.\n *\n * Currently wired ONLY into the v3 Drizzle adapter (`eql/v3/drizzle/operators`).\n * It lives here, beside the shared match defaults, because v2 builds the same\n * bloom filters and needs the same floor — but v2's `like`/`ilike` path remains\n * unguarded and still fails open. Do not reuse this for v2 without first\n * measuring what its tokenizer actually receives: v2 needles carry SQL wildcards\n * (`'%ada%'`), so the floor may have to apply to the unwrapped term rather than\n * to the string the caller passed.\n */\nexport function matchNeedleError(\n  needle: unknown,\n  opts: MatchIndexOpts,\n): string | undefined {\n  if (typeof needle !== 'string') return undefined\n\n  // Codepoints, not UTF-16 code units — see above.\n  const length = [...needle].length\n  const min = matchNeedleMinLength(opts)\n\n  if (length === 0) {\n    return `free-text search needs a non-empty search term; an empty term produces no tokens and would match every row.`\n  }\n  if (min === undefined || length >= min) return undefined\n  return `free-text search needs at least ${min} characters (the index tokenizer's token_length), but the search term ${JSON.stringify(needle)} has ${length}. A shorter term produces no tokens and would match every row.`\n}\n"],"mappings":";AAyCO,SAAS,mBAAwC;AACtD,SAAO;AAAA,IACL,WAAW,EAAE,MAAM,SAAS,cAAc,EAAE;AAAA,IAC5C,eAAe,CAAC,EAAE,MAAM,WAAW,CAAC;AAAA,IACpC,GAAG;AAAA,IACH,GAAG;AAAA,IACH,kBAAkB;AAAA,EACpB;AACF;AAOO,SAAS,eAAe,MAAgD;AAC7E,SAAO;AAAA,IACL,GAAG;AAAA,IACH,WAAW,EAAE,GAAG,KAAK,UAAU;AAAA,IAC/B,eAAe,KAAK,cAAc,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE;AAAA,EACzD;AACF;AAaO,SAAS,iBAAiB,MAA4C;AAC3E,QAAM,WAAW,iBAAiB;AAClC,SAAO,eAAe;AAAA,IACpB,WAAW,MAAM,aAAa,SAAS;AAAA,IACvC,eAAe,MAAM,iBAAiB,SAAS;AAAA,IAC/C,GAAG,MAAM,KAAK,SAAS;AAAA,IACvB,GAAG,MAAM,KAAK,SAAS;AAAA,IACvB,kBAAkB,MAAM,oBAAoB,SAAS;AAAA,EACvD,CAAC;AACH;AAaO,SAAS,qBAAqB,MAA0C;AAC7E,QAAM,YAAY,KAAK,aAAa,iBAAiB,EAAE;AACvD,SAAO,UAAU,SAAS,UAAU,UAAU,eAAe;AAC/D;AA8BO,SAAS,iBACd,QACA,MACoB;AACpB,MAAI,OAAO,WAAW,SAAU,QAAO;AAGvC,QAAM,SAAS,CAAC,GAAG,MAAM,EAAE;AAC3B,QAAM,MAAM,qBAAqB,IAAI;AAErC,MAAI,WAAW,GAAG;AAChB,WAAO;AAAA,EACT;AACA,MAAI,QAAQ,UAAa,UAAU,IAAK,QAAO;AAC/C,SAAO,mCAAmC,GAAG,yEAAyE,KAAK,UAAU,MAAM,CAAC,QAAQ,MAAM;AAC5J;","names":[]}

package/dist/{chunk-XWPGAHBZ.js → chunk-BNO32ZMV.js}

@@ -58,4 +58,4 @@ export {
   toFfiKeysetIdentifier,
   isEncryptedPayload
 };
-//# sourceMappingURL=chunk-XWPGAHBZ.js.map
+//# sourceMappingURL=chunk-BNO32ZMV.js.map

package/dist/chunk-BNO32ZMV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/encryption/helpers/index.ts"],"sourcesContent":["import type {\n  Encrypted as CipherStashEncrypted,\n  EncryptedQuery as CipherStashEncryptedQuery,\n  EncryptedV3Query as CipherStashEncryptedV3Query,\n  KeysetIdentifier as KeysetIdentifierFfi,\n} from '@cipherstash/protect-ffi'\nimport type { Encrypted, EncryptedQueryResult, KeysetIdentifier } from '@/types'\n\n/**\n * The shape `encryptQuery` / `encryptQueryBulk` can return: a full storage\n * payload (returned for v2 `ste_vec_term` containment queries), a query-only\n * payload with no ciphertext (scalar `unique`/`match`/`ore` lookups and\n * `ste_vec_selector` path queries), or — under `eqlVersion: 3` — the\n * `eql_v3.jsonb_query` containment needle.\n *\n * TODO: duplicated in `@cipherstash/protect` — see\n * `packages/protect/src/helpers/index.ts`. Both copies should be removed once\n * `@cipherstash/protect-ffi` exports a named alias for the `encryptQuery`\n * return type (https://github.com/cipherstash/stack/pull/473).\n */\ntype EncryptedQueryTerm =\n  | CipherStashEncrypted\n  | CipherStashEncryptedQuery\n  | CipherStashEncryptedV3Query\n\nexport type EncryptedPgComposite = {\n  data: Encrypted\n}\n\n/**\n * Helper function to transform an encrypted payload into a PostgreSQL composite type.\n * Use this when inserting data via Supabase or similar clients.\n */\nexport function encryptedToPgComposite(obj: Encrypted): EncryptedPgComposite {\n  return {\n    data: obj,\n  }\n}\n\n/**\n * Helper function to transform an encrypted payload into a PostgreSQL composite literal string.\n * Use this when querying with `.eq()` or similar equality operations in Supabase.\n *\n * @example\n * ```typescript\n * const literal = encryptedToCompositeLiteral(encrypted)\n * await supabase.from('table').select().eq('column', literal)\n * ```\n */\nexport function encryptedToCompositeLiteral(obj: EncryptedQueryTerm): string {\n  return `(${JSON.stringify(JSON.stringify(obj))})`\n}\n\n/**\n * Helper function to transform an encrypted payload into an escaped PostgreSQL composite literal string.\n * Use this when you need the composite literal format to be escaped as a string value.\n *\n * @example\n * ```typescript\n * const escapedLiteral = encryptedToEscapedCompositeLiteral(encrypted)\n * ```\n */\nexport function encryptedToEscapedCompositeLiteral(\n  obj: EncryptedQueryTerm,\n): string {\n  return JSON.stringify(encryptedToCompositeLiteral(obj))\n}\n\n/**\n * Format an encrypted result based on the requested return type.\n *\n * - `'composite-literal'` → PostgreSQL composite literal string `(\"json\")`\n * - `'escaped-composite-literal'` → escaped variant `\"(\\\"json\\\")\"`\n * - default (`'eql'` or omitted) → raw encrypted object\n */\nexport function formatEncryptedResult(\n  encrypted: EncryptedQueryTerm,\n  returnType?: string,\n): EncryptedQueryResult {\n  if (returnType === 'composite-literal') {\n    return encryptedToCompositeLiteral(encrypted)\n  }\n  if (returnType === 'escaped-composite-literal') {\n    return encryptedToEscapedCompositeLiteral(encrypted)\n  }\n  return encrypted\n}\n\n/**\n * Helper function to transform a model's encrypted fields into PostgreSQL composite types\n */\nexport function modelToEncryptedPgComposites<T extends Record<string, unknown>>(\n  model: T,\n): T {\n  const result: Record<string, unknown> = {}\n\n  for (const [key, value] of Object.entries(model)) {\n    if (isEncryptedPayload(value)) {\n      result[key] = encryptedToPgComposite(value)\n    } else {\n      result[key] = value\n    }\n  }\n\n  return result as T\n}\n\n/**\n * Helper function to transform multiple models' encrypted fields into PostgreSQL composite types\n */\nexport function bulkModelsToEncryptedPgComposites<\n  T extends Record<string, unknown>,\n>(models: T[]): T[] {\n  return models.map((model) => modelToEncryptedPgComposites(model))\n}\n\nexport function toFfiKeysetIdentifier(\n  keyset: KeysetIdentifier | undefined,\n): KeysetIdentifierFfi | undefined {\n  if (!keyset) return undefined\n\n  if ('name' in keyset) {\n    return { Name: keyset.name }\n  }\n\n  return { Uuid: keyset.id }\n}\n\n/**\n * Helper function to check if a value is an encrypted payload\n */\nexport function isEncryptedPayload(value: unknown): value is Encrypted {\n  if (value === null) return false\n  if (typeof value !== 'object') return false\n\n  const obj = value as Record<string, unknown>\n\n  // Must have version field (number)\n  if (!('v' in obj) || typeof obj.v !== 'number') return false\n\n  // Must have index field (object)\n  if (!('i' in obj) || typeof obj.i !== 'object') return false\n\n  // Must have either ciphertext (c) or searchable vector (sv)\n  if (!('c' in obj) && !('sv' in obj)) return false\n\n  return true\n}\n\nexport {\n  buildNestedObject,\n  parseJsonbPath,\n  toJsonPath,\n} from './jsonb'\n"],"mappings":";AAiCO,SAAS,uBAAuB,KAAsC;AAC3E,SAAO;AAAA,IACL,MAAM;AAAA,EACR;AACF;AAYO,SAAS,4BAA4B,KAAiC;AAC3E,SAAO,IAAI,KAAK,UAAU,KAAK,UAAU,GAAG,CAAC,CAAC;AAChD;AAWO,SAAS,mCACd,KACQ;AACR,SAAO,KAAK,UAAU,4BAA4B,GAAG,CAAC;AACxD;AASO,SAAS,sBACd,WACA,YACsB;AACtB,MAAI,eAAe,qBAAqB;AACtC,WAAO,4BAA4B,SAAS;AAAA,EAC9C;AACA,MAAI,eAAe,6BAA6B;AAC9C,WAAO,mCAAmC,SAAS;AAAA,EACrD;AACA,SAAO;AACT;AAKO,SAAS,6BACd,OACG;AACH,QAAM,SAAkC,CAAC;AAEzC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,mBAAmB,KAAK,GAAG;AAC7B,aAAO,GAAG,IAAI,uBAAuB,KAAK;AAAA,IAC5C,OAAO;AACL,aAAO,GAAG,IAAI;AAAA,IAChB;AAAA,EACF;AAEA,SAAO;AACT;AAKO,SAAS,kCAEd,QAAkB;AAClB,SAAO,OAAO,IAAI,CAAC,UAAU,6BAA6B,KAAK,CAAC;AAClE;AAEO,SAAS,sBACd,QACiC;AACjC,MAAI,CAAC,OAAQ,QAAO;AAEpB,MAAI,UAAU,QAAQ;AACpB,WAAO,EAAE,MAAM,OAAO,KAAK;AAAA,EAC7B;AAEA,SAAO,EAAE,MAAM,OAAO,GAAG;AAC3B;AAKO,SAAS,mBAAmB,OAAoC;AACrE,MAAI,UAAU,KAAM,QAAO;AAC3B,MAAI,OAAO,UAAU,SAAU,QAAO;AAEtC,QAAM,MAAM;AAGZ,MAAI,EAAE,OAAO,QAAQ,OAAO,IAAI,MAAM,SAAU,QAAO;AAGvD,MAAI,EAAE,OAAO,QAAQ,OAAO,IAAI,MAAM,SAAU,QAAO;AAGvD,MAAI,EAAE,OAAO,QAAQ,EAAE,QAAQ,KAAM,QAAO;AAE5C,SAAO;AACT;","names":[]}