flagmint-js-sdk 2.2.1 → 2.2.2

package/dist/index.d.ts

@@ -12,5 +12,5 @@ export { evaluateFlagValue } from './sdk/core/evaluation/evaluateFlagValue';
 export { evaluateRollout } from './sdk/core/evaluation/evaluateRollout';
 export { isInSegment } from './sdk/core/evaluation/isInSegment';
 export * from './sdk/core/evaluation/rolloutUtils';
-export { RulesStore, createEmptyRulesState, reduceRules, performAslHandshake, generateAslClientKeyPair, deriveAslMacKey, signConfigPayload, verifyConfigPayloadSignature, canonicalizeForSigning, isConfigPayloadExpired, evaluateSdkFlag, evaluateAllSdkFlags, coerceType, evaluateRule, evaluateFlagWithTargetingRules, applyRolloutStrategy, computeCurrentPercentage, defaultHash, flattenEvaluationContext, stringHash, hashPercent, } from './sdk/core/config-sync';
-export type { SdkFlagConfig, SdkSegment, RulesState, RulesCacheSnapshot, ConfigSyncPayload, LeasePayload, FullConfigPayload, DeltaConfigPayload, DeltasCatchUpPayload, ApplyResult, AslHandshakeSuccess, } from './sdk/core/config-sync';
+export { RulesStore, createEmptyRulesState, reduceRules, performAslHandshake, generateAslClientKeyPair, deriveAslMacKey, signConfigPayload, verifyConfigPayloadSignature, canonicalizeForSigning, isConfigPayloadExpired, evaluateSdkFlag, evaluateAllSdkFlags, coerceType, evaluateRule, evaluateFlagWithTargetingRules, applyRolloutStrategy, computeCurrentPercentage, defaultHash, flattenEvaluationContext, prepareContextForLocalEval, hashPiiValue, applyPiiHashToFlatContext, stringHash, hashPercent, } from './sdk/core/config-sync';
+export type { SdkFlagConfig, SdkSegment, RulesState, RulesCacheSnapshot, ConfigSyncPayload, LeasePayload, FullConfigPayload, DeltaConfigPayload, DeltasCatchUpPayload, ApplyResult, AslHandshakeSuccess, PiiWireOptions, } from './sdk/core/config-sync';

package/dist/sdk/core/config-sync/evaluateSdkFlag.d.ts

@@ -3,6 +3,7 @@
  * using the ported `flagEvaluator` (spec = utils/flag-evaluator.ts).
  */
 import { type FlagEvaluationResult } from './flagEvaluator';
+import { type PiiWireOptions } from './piiHash';
 import type { SdkFlagConfig, SdkSegment } from './types';
 /** ES2018-safe Map → record (avoids Object.fromEntries / ES2019 lib). */
 export declare function mapToRecord<V>(map: Map<string, V>): Record<string, V>;
@@ -16,11 +17,33 @@ export declare function mapToRecord<V>(map: Map<string, V>): Record<string, V>;
  *   and organization is not dropped.
  */
 export declare function prepareContextForEvaluator(context: Record<string, unknown> | null | undefined): Record<string, unknown>;
+/**
+ * Flatten prepared context, then hash PII fields so they match hashed rule
+ * values on the config-sync wire (FF-EU Phase B / SDK Phase C).
+ *
+ * @param context Evaluation or flat context
+ * @param pii PII wire options from the rules store (null/undefined = no-op)
+ */
+export declare function prepareContextForLocalEval(context: Record<string, unknown> | null | undefined, pii?: PiiWireOptions | null): Record<string, unknown>;
 /**
  * Evaluate one SdkFlagConfig against context (server RuleEngine order).
+ *
+ * @param flag Compiled flag config
+ * @param context Evaluation context (plaintext PII is hashed when `pii` is set)
+ * @param segments Segment map for segment rules
+ * @param pii Optional PII wire options from the signed config
+ */
+export declare function evaluateSdkFlag(flag: SdkFlagConfig, context: Record<string, unknown>, segments: Map<string, SdkSegment> | Record<string, SdkSegment>, pii?: PiiWireOptions | null): FlagEvaluationResult;
+/**
+ * Evaluate every flag in a map/list against one context.
+ *
+ * @param flags Flag configs
+ * @param context Shared evaluation context
+ * @param segments Segment map
+ * @param options Fail-closed and PII wire options
  */
-export declare function evaluateSdkFlag(flag: SdkFlagConfig, context: Record<string, unknown>, segments: Map<string, SdkSegment> | Record<string, SdkSegment>): FlagEvaluationResult;
 export declare function evaluateAllSdkFlags<T = unknown>(flags: Map<string, SdkFlagConfig> | SdkFlagConfig[], context: Record<string, unknown>, segments: Map<string, SdkSegment> | Record<string, SdkSegment>, options?: {
     failClosedDefaultsOnly?: boolean;
+    pii?: PiiWireOptions | null;
 }): Record<string, T>;
 export { coerceType } from './flagEvaluator';

package/dist/sdk/core/config-sync/index.d.ts

@@ -3,10 +3,12 @@ export type { AslClientKeyPair, AslDerivedMac } from './aslEcdh';
 export { canonicalizeForSigning, isConfigPayloadExpired, signConfigPayload, verifyConfigPayloadSignature, } from './signPayload';
 export { RulesStore, createEmptyRulesState, reduceRules, } from './rulesStore';
 export type { ApplyResult, RulesState } from './rulesStore';
-export type { ConfigSyncPayload, DeltaConfigPayload, DeltasCatchUpPayload, FullConfigPayload, LeasePayload, RulesCacheSnapshot, SdkFlagConfig, SdkSegment, SignableConfigBody, } from './types';
+export type { ConfigSyncPayload, DeltaConfigPayload, DeltasCatchUpPayload, FullConfigPayload, LeasePayload, PiiWireMetadata, RulesCacheSnapshot, SdkFlagConfig, SdkSegment, SignableConfigBody, } from './types';
 export { performAslHandshake } from './handshake';
 export type { AslHandshakeSuccess } from './handshake';
-export { evaluateSdkFlag, evaluateAllSdkFlags, coerceType, prepareContextForEvaluator, mapToRecord, } from './evaluateSdkFlag';
+export { evaluateSdkFlag, evaluateAllSdkFlags, coerceType, prepareContextForEvaluator, prepareContextForLocalEval, mapToRecord, } from './evaluateSdkFlag';
+export { PII_VALUE_ENCODING, normalizePiiString, hashPiiValue, isPiiAttribute, payloadHasExplicitPiiFields, piiWireOptionsFromPayload, resolvePiiWireForDelta, applyPiiHashToFlatContext, } from './piiHash';
+export type { PiiWireOptions, ApplyPiiHashMode } from './piiHash';
 export { evaluateRule, evaluateKillSwitch, evaluateOnVariation, evaluateFlagWithTargetingRules, applyRolloutStrategy, applyPercentageRollout, applyVariantRollout, applyGradualRollout, computeCurrentPercentage, defaultHash, getContextAttribute, } from './flagEvaluator';
 export type { ExpectedFlagType, FlagEvaluationResult, Condition, TargetingRule, Rollout, Variation, Segment, EvaluationDeps, } from './flagEvaluator';
 export { flattenContext, flattenEvaluationContext } from './flattenContext';

package/dist/sdk/core/config-sync/piiHash.d.ts

@@ -0,0 +1,87 @@
+/** Must match FF-EU `PII_VALUE_ENCODING`. */
+export declare const PII_VALUE_ENCODING: "hmac-v1";
+/**
+ * Client PII wire options from signed `fullConfig` / `delta`.
+ */
+export type PiiWireOptions = {
+    piiAttributes: string[];
+    piiSalt: string;
+    piiValueEncoding?: typeof PII_VALUE_ENCODING | string;
+};
+/**
+ * Extra apply options. Prefer plaintext context; only set `alreadyHashed`
+ * when callers intentionally supply wire digests (do not infer from hex shape).
+ */
+export type ApplyPiiHashMode = {
+    /** When true, leave PII string fields unchanged (caller supplied digests). */
+    alreadyHashed?: boolean;
+};
+/**
+ * Normalize a string before PII hashing (trim + lowercase).
+ * Must match FF-EU `normalizePiiString`.
+ *
+ * @param value Raw attribute value
+ */
+export declare function normalizePiiString(value: string): string;
+/**
+ * HMAC-SHA256 hex digest of a normalized PII string.
+ * Must match FF-EU `hashPiiValue`.
+ *
+ * @param value Plaintext value
+ * @param salt Client-visible salt from the signed config
+ */
+export declare function hashPiiValue(value: string, salt: string): string;
+/**
+ * Whether a context / rule attribute key is PII.
+ * Matches bare keys (`email`) and kind-prefixed forms (`user.email`).
+ *
+ * @param attribute Attribute key from context or rule
+ * @param piiAttributes Keys from signed config
+ */
+export declare function isPiiAttribute(attribute: string | undefined | null, piiAttributes: readonly string[]): boolean;
+/** Payload fields that carry PII wire metadata. */
+export type PiiWirePayloadFields = {
+    piiAttributes?: unknown;
+    piiSalt?: unknown;
+    piiValueEncoding?: unknown;
+};
+/**
+ * Whether a payload explicitly includes any PII wire field (vs omitting all).
+ * Used so deltas that omit PII metadata keep the previous options, while
+ * deltas that send unusable fields clear them.
+ *
+ * @param payload Signed fullConfig / delta fields
+ */
+export declare function payloadHasExplicitPiiFields(payload: PiiWirePayloadFields | null | undefined): boolean;
+/**
+ * Parse PII wire options from a config-sync payload body.
+ *
+ * @param payload Signed fullConfig / delta fields
+ * @returns Options when salt + encoding are usable; otherwise null
+ */
+export declare function piiWireOptionsFromPayload(payload: PiiWirePayloadFields | null | undefined): PiiWireOptions | null;
+/**
+ * Resolve PII wire options for a delta: keep prior when all PII fields are
+ * absent; otherwise parse after merging omitted fields from `previous`.
+ *
+ * FF-EU `piiMetadata` always emits the full triple (or nothing). Merge is
+ * defensive so a salt-only / attrs-only delta cannot wipe the other fields.
+ * Explicit empty salt or unknown encoding still clears to null.
+ *
+ * @param previous Current store options
+ * @param action Delta (or similar) payload fields
+ */
+export declare function resolvePiiWireForDelta(previous: PiiWireOptions | null, action: PiiWirePayloadFields | null | undefined): PiiWireOptions | null;
+/**
+ * Hash PII string fields on a flat evaluation context so they match hashed
+ * rule values on the wire.
+ *
+ * Always hashes plaintext strings (including values that look like 64-char hex).
+ * Pass `{ alreadyHashed: true }` only when the caller already supplied digests.
+ *
+ * @param context Flat context map (after prepare / flatten)
+ * @param options PII options from the rules store
+ * @param mode Optional apply mode (`alreadyHashed` skips hashing)
+ * @returns New context object with PII strings hashed (or the input if no-op)
+ */
+export declare function applyPiiHashToFlatContext(context: Record<string, unknown>, options: PiiWireOptions | null | undefined, mode?: ApplyPiiHashMode): Record<string, unknown>;

package/dist/sdk/core/config-sync/rulesStore.d.ts

@@ -1,3 +1,4 @@
+import { type PiiWireOptions } from './piiHash';
 import type { ConfigSyncPayload, DeltaConfigPayload, DeltasCatchUpPayload, FullConfigPayload, LeasePayload, RulesCacheSnapshot, SdkFlagConfig, SdkSegment } from './types';
 export type RulesState = {
     version: number;
@@ -8,6 +9,8 @@ export type RulesState = {
     ready: boolean;
     /** Set when a delta's fromVersion does not match — reconnect with fullConfig. */
     needsFullConfig: boolean;
+    /** PII hash options from the last fullConfig/delta (null when absent). */
+    piiWire: PiiWireOptions | null;
 };
 export type ApplyResult = {
     ok: true;

package/dist/sdk/core/config-sync/types.d.ts

@@ -33,6 +33,12 @@ export type LeasePayload = {
     expiresAt: number;
     signature: string;
 };
+/** PII hashing metadata on client-bound config (FF-EU Phase B). */
+export type PiiWireMetadata = {
+    piiAttributes?: string[];
+    piiSalt?: string;
+    piiValueEncoding?: string;
+};
 export type FullConfigPayload = {
     type: 'fullConfig';
     version: number;
@@ -42,7 +48,7 @@ export type FullConfigPayload = {
     segments: Record<string, SdkSegment>;
     warnings?: string[];
     signature: string;
-};
+} & PiiWireMetadata;
 export type DeltaConfigPayload = {
     type: 'delta';
     fromVersion: number;
@@ -53,7 +59,7 @@ export type DeltaConfigPayload = {
     deletes: string[];
     segments: Record<string, SdkSegment>;
     signature: string;
-};
+} & PiiWireMetadata;
 export type DeltasCatchUpPayload = {
     type: 'deltas';
     fromVersion: number;
@@ -69,4 +75,8 @@ export type RulesCacheSnapshot = {
     expiresAt: number;
     flags: SdkFlagConfig[];
     segments: Record<string, SdkSegment>;
+    /** PII wire options so offline hydrate still hashes context correctly. */
+    piiAttributes?: string[];
+    piiSalt?: string;
+    piiValueEncoding?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flagmint-js-sdk",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "Framework-agnostic JavaScript SDK for managing feature flags in Flagmint applications.",
   "author": "Flagmint Team",
   "license": "BSD 3-Clause",