@nebulr-group/bridge-auth-core 0.1.2 → 0.4.0-beta.0

package/dist/flags/operators.d.ts

@@ -0,0 +1,63 @@
+export declare const OPERATORS: readonly ["eq", "neq", "contains", "not_contains", "in", "not_in", "gt", "lt", "between", "regex", "exists", "not_exists"];
+export type Operator = (typeof OPERATORS)[number];
+export declare const OPERATOR_VERSION: 1;
+export type AttributeType = 'string' | 'number' | 'boolean' | 'date';
+export declare function isOperator(value: unknown): value is Operator;
+export declare function isOperatorValidForType(op: Operator, type: AttributeType): boolean;
+export declare function validOperatorsForType(type: AttributeType): ReadonlyArray<Operator>;
+export declare const CONDITIONS_PER_RULE_MAX = 50;
+export type ConditionValue = string | number | boolean | null;
+export interface Condition {
+    attribute: string;
+    operator: Operator;
+    values: ReadonlyArray<ConditionValue>;
+}
+/**
+ * Evaluate a single condition against an attribute value.
+ *
+ * @param condition       The condition (attribute, operator, values) from the rule.
+ * @param attributeValue  The value of the named attribute in the eval context.
+ *                        May be undefined / null if the SDK didn't supply it.
+ * @returns true if the condition matches; false otherwise.
+ *
+ * Operator semantics:
+ *   eq            attributeValue === values[0]
+ *   neq           attributeValue !== values[0]
+ *   contains      String(attributeValue).includes(String(values[0]))
+ *   not_contains  ! contains
+ *   in            values.includes(attributeValue)
+ *   not_in        ! in
+ *   gt            Number(attributeValue) > Number(values[0])
+ *   lt            Number(attributeValue) < Number(values[0])
+ *   between       Number(values[0]) <= Number(attributeValue) <= Number(values[1])
+ *                 (values[0] and values[1] are auto-swapped if out of order)
+ *   regex         new RegExp(String(values[0])).test(String(attributeValue))
+ *   exists        attributeValue !== undefined && attributeValue !== null
+ *   not_exists    ! exists
+ *
+ * Fail-safe rule: any malformed input (wrong number of values, non-numeric
+ * value for a numeric operator, invalid regex, oversized input) returns false
+ * rather than throwing. The server must still validate at save time; this
+ * function is intentionally lenient at runtime so a bad rule never crashes
+ * the consuming app.
+ */
+export declare function evaluateCondition(condition: Condition, attributeValue: unknown): boolean;
+export interface ValidationError {
+    /** Index of the condition within its containing branch (or -1 if global). */
+    conditionIndex: number;
+    attribute: string;
+    operator: Operator;
+    message: string;
+}
+/**
+ * Validate a list of conditions against a known attribute type map at save time.
+ *
+ * @param conditions       The conditions to validate (e.g. a branch's `conditions`).
+ * @param attributeTypes   Map of attribute key → known type. If an attribute is
+ *                         not in the map its type is treated as unknown and
+ *                         validation only checks operator membership in the
+ *                         locked set (not type compatibility).
+ * @returns list of validation errors; empty list means valid.
+ */
+export declare function validateConditions(conditions: ReadonlyArray<Condition>, attributeTypes?: Readonly<Record<string, AttributeType>>): ValidationError[];
+//# sourceMappingURL=operators.d.ts.map

package/dist/flags/operators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operators.d.ts","sourceRoot":"","sources":["../../src/flags/operators.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,SAAS,4HAaZ,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAElD,eAAO,MAAM,gBAAgB,EAAG,CAAU,CAAC;AAE3C,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAarE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAEjF;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAAC,QAAQ,CAAC,CAElF;AAqBD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAI1C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE9D,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACvC;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CA4FxF;AAID,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,EACpC,cAAc,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAM,GAC3D,eAAe,EAAE,CAwGnB"}

package/dist/flags/operators.js

@@ -0,0 +1,299 @@
+// The locked operator set for Bridge Feature Flags v1.
+//
+// This module is the SINGLE SOURCE OF TRUTH for both:
+//   - bridge-api server-side rule evaluation
+//   - bridge-* SDK client-side rule evaluation (via auth-core)
+//
+// Adding or removing an operator is a breaking change of the v1 contract.
+// The `OPERATOR_VERSION` constant is forward-compat space — a stored rule
+// carries the operator-set version it was authored against, so future
+// expansions of the closed set can be migrated cleanly.
+export const OPERATORS = [
+    'eq',
+    'neq',
+    'contains',
+    'not_contains',
+    'in',
+    'not_in',
+    'gt',
+    'lt',
+    'between',
+    'regex',
+    'exists',
+    'not_exists',
+];
+export const OPERATOR_VERSION = 1;
+// Which operators are valid for which attribute type. Used by:
+//   - Server-side save-time validation (reject mixed-type rules)
+//   - Admin UI operator picker (filter dropdown by attribute type)
+//   - SDK eval (defensive — should already be validated server-side)
+const VALID_OPERATORS_BY_TYPE = {
+    string: ['eq', 'neq', 'contains', 'not_contains', 'in', 'not_in', 'regex', 'exists', 'not_exists'],
+    number: ['eq', 'neq', 'gt', 'lt', 'between', 'in', 'not_in', 'exists', 'not_exists'],
+    boolean: ['eq', 'neq', 'exists', 'not_exists'],
+    date: ['eq', 'neq', 'gt', 'lt', 'between', 'exists', 'not_exists'],
+};
+export function isOperator(value) {
+    return typeof value === 'string' && OPERATORS.includes(value);
+}
+export function isOperatorValidForType(op, type) {
+    return VALID_OPERATORS_BY_TYPE[type]?.includes(op) ?? false;
+}
+export function validOperatorsForType(type) {
+    return VALID_OPERATORS_BY_TYPE[type] ?? [];
+}
+// ── Safety limits ───────────────────────────────────────────────────────────
+//
+// Bounds on inputs that protect against denial-of-service or pathological
+// rules. These are deliberately generous — they exist to draw a line, not to
+// constrain reasonable use. Anything beyond these limits is treated as a
+// non-match rather than evaluated (fail-safe).
+// Cap regex input length to mitigate ReDoS on malicious patterns. Inputs
+// longer than this are treated as non-matching rather than evaluated.
+// Note: a real sandboxed regex engine (e.g. re2-wasm) is a future hardening
+// step. v1 caps input + uses try/catch around the standard engine.
+const REGEX_INPUT_MAX = 10_000;
+// Hard cap on the number of items in `in` / `not_in` value arrays.
+const IN_LIST_MAX = 1_000;
+// Hard cap on the number of conditions allowed in a single rule (across
+// all branches combined). Enforced at save time by the server, exposed here
+// so the UI can surface the limit consistently.
+export const CONDITIONS_PER_RULE_MAX = 50;
+// ── Evaluation ──────────────────────────────────────────────────────────────
+/**
+ * Evaluate a single condition against an attribute value.
+ *
+ * @param condition       The condition (attribute, operator, values) from the rule.
+ * @param attributeValue  The value of the named attribute in the eval context.
+ *                        May be undefined / null if the SDK didn't supply it.
+ * @returns true if the condition matches; false otherwise.
+ *
+ * Operator semantics:
+ *   eq            attributeValue === values[0]
+ *   neq           attributeValue !== values[0]
+ *   contains      String(attributeValue).includes(String(values[0]))
+ *   not_contains  ! contains
+ *   in            values.includes(attributeValue)
+ *   not_in        ! in
+ *   gt            Number(attributeValue) > Number(values[0])
+ *   lt            Number(attributeValue) < Number(values[0])
+ *   between       Number(values[0]) <= Number(attributeValue) <= Number(values[1])
+ *                 (values[0] and values[1] are auto-swapped if out of order)
+ *   regex         new RegExp(String(values[0])).test(String(attributeValue))
+ *   exists        attributeValue !== undefined && attributeValue !== null
+ *   not_exists    ! exists
+ *
+ * Fail-safe rule: any malformed input (wrong number of values, non-numeric
+ * value for a numeric operator, invalid regex, oversized input) returns false
+ * rather than throwing. The server must still validate at save time; this
+ * function is intentionally lenient at runtime so a bad rule never crashes
+ * the consuming app.
+ */
+export function evaluateCondition(condition, attributeValue) {
+    const { operator, values } = condition;
+    // exists / not_exists handle missing values specially — short-circuit first
+    if (operator === 'exists') {
+        return attributeValue !== undefined && attributeValue !== null;
+    }
+    if (operator === 'not_exists') {
+        return attributeValue === undefined || attributeValue === null;
+    }
+    // For every other operator: a missing attribute is always a non-match
+    if (attributeValue === undefined || attributeValue === null) {
+        return false;
+    }
+    switch (operator) {
+        case 'eq':
+            return values.length > 0 && values[0] === attributeValue;
+        case 'neq':
+            return values.length > 0 && values[0] !== attributeValue;
+        case 'contains': {
+            if (values.length === 0)
+                return false;
+            return String(attributeValue).includes(String(values[0]));
+        }
+        case 'not_contains': {
+            if (values.length === 0)
+                return false;
+            return !String(attributeValue).includes(String(values[0]));
+        }
+        case 'in': {
+            if (values.length === 0 || values.length > IN_LIST_MAX)
+                return false;
+            return values.includes(attributeValue);
+        }
+        case 'not_in': {
+            // An empty `not_in` list is vacuously true (no values to exclude).
+            if (values.length > IN_LIST_MAX)
+                return false;
+            return !values.includes(attributeValue);
+        }
+        case 'gt': {
+            if (values.length === 0)
+                return false;
+            const n = Number(attributeValue);
+            const t = Number(values[0]);
+            if (Number.isNaN(n) || Number.isNaN(t))
+                return false;
+            return n > t;
+        }
+        case 'lt': {
+            if (values.length === 0)
+                return false;
+            const n = Number(attributeValue);
+            const t = Number(values[0]);
+            if (Number.isNaN(n) || Number.isNaN(t))
+                return false;
+            return n < t;
+        }
+        case 'between': {
+            if (values.length < 2)
+                return false;
+            const n = Number(attributeValue);
+            const a = Number(values[0]);
+            const b = Number(values[1]);
+            if (Number.isNaN(n) || Number.isNaN(a) || Number.isNaN(b))
+                return false;
+            const [lo, hi] = a <= b ? [a, b] : [b, a];
+            return n >= lo && n <= hi;
+        }
+        case 'regex': {
+            if (values.length === 0)
+                return false;
+            const input = String(attributeValue);
+            if (input.length > REGEX_INPUT_MAX)
+                return false;
+            try {
+                const re = new RegExp(String(values[0]));
+                return re.test(input);
+            }
+            catch {
+                // Invalid regex pattern — fail-safe: treat as non-match.
+                return false;
+            }
+        }
+        default: {
+            // Exhaustiveness check — `operator` is typed as Operator, so this
+            // branch should be unreachable. If it's hit, the rule was authored
+            // against a future operator set and we should fail-safe.
+            const _exhaustive = operator;
+            void _exhaustive;
+            return false;
+        }
+    }
+}
+/**
+ * Validate a list of conditions against a known attribute type map at save time.
+ *
+ * @param conditions       The conditions to validate (e.g. a branch's `conditions`).
+ * @param attributeTypes   Map of attribute key → known type. If an attribute is
+ *                         not in the map its type is treated as unknown and
+ *                         validation only checks operator membership in the
+ *                         locked set (not type compatibility).
+ * @returns list of validation errors; empty list means valid.
+ */
+export function validateConditions(conditions, attributeTypes = {}) {
+    const errors = [];
+    conditions.forEach((c, i) => {
+        if (!isOperator(c.operator)) {
+            errors.push({
+                conditionIndex: i,
+                attribute: c.attribute,
+                operator: c.operator,
+                message: `Unknown operator "${c.operator}". Valid operators: ${OPERATORS.join(', ')}.`,
+            });
+            return;
+        }
+        // Per-operator structural validation
+        switch (c.operator) {
+            case 'between':
+                if (c.values.length !== 2) {
+                    errors.push({
+                        conditionIndex: i,
+                        attribute: c.attribute,
+                        operator: c.operator,
+                        message: `Operator "between" requires exactly 2 values, got ${c.values.length}.`,
+                    });
+                }
+                break;
+            case 'in':
+            case 'not_in':
+                if (c.values.length === 0) {
+                    errors.push({
+                        conditionIndex: i,
+                        attribute: c.attribute,
+                        operator: c.operator,
+                        message: `Operator "${c.operator}" requires at least 1 value.`,
+                    });
+                }
+                else if (c.values.length > IN_LIST_MAX) {
+                    errors.push({
+                        conditionIndex: i,
+                        attribute: c.attribute,
+                        operator: c.operator,
+                        message: `Operator "${c.operator}" supports at most ${IN_LIST_MAX} values, got ${c.values.length}.`,
+                    });
+                }
+                break;
+            case 'exists':
+            case 'not_exists':
+                if (c.values.length !== 0) {
+                    errors.push({
+                        conditionIndex: i,
+                        attribute: c.attribute,
+                        operator: c.operator,
+                        message: `Operator "${c.operator}" takes no values, got ${c.values.length}.`,
+                    });
+                }
+                break;
+            case 'regex':
+                if (c.values.length !== 1) {
+                    errors.push({
+                        conditionIndex: i,
+                        attribute: c.attribute,
+                        operator: c.operator,
+                        message: `Operator "regex" requires exactly 1 value, got ${c.values.length}.`,
+                    });
+                }
+                else {
+                    try {
+                        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                        const _ = new RegExp(String(c.values[0]));
+                    }
+                    catch (e) {
+                        const msg = e instanceof Error ? e.message : String(e);
+                        errors.push({
+                            conditionIndex: i,
+                            attribute: c.attribute,
+                            operator: c.operator,
+                            message: `Invalid regex pattern: ${msg}`,
+                        });
+                    }
+                }
+                break;
+            default:
+                // Most binary operators expect exactly 1 value
+                if (c.values.length !== 1) {
+                    errors.push({
+                        conditionIndex: i,
+                        attribute: c.attribute,
+                        operator: c.operator,
+                        message: `Operator "${c.operator}" requires exactly 1 value, got ${c.values.length}.`,
+                    });
+                }
+                break;
+        }
+        // Type-vs-operator compatibility (only when the attribute's type is known)
+        const type = attributeTypes[c.attribute];
+        if (type && !isOperatorValidForType(c.operator, type)) {
+            errors.push({
+                conditionIndex: i,
+                attribute: c.attribute,
+                operator: c.operator,
+                message: `Operator "${c.operator}" cannot be used with attribute "${c.attribute}" of type ${type}. Valid operators for ${type}: ${validOperatorsForType(type).join(', ')}.`,
+            });
+        }
+    });
+    return errors;
+}
+//# sourceMappingURL=operators.js.map

package/dist/flags/operators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operators.js","sourceRoot":"","sources":["../../src/flags/operators.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,sDAAsD;AACtD,6CAA6C;AAC7C,+DAA+D;AAC/D,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,sEAAsE;AACtE,wDAAwD;AAExD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI;IACJ,KAAK;IACL,UAAU;IACV,cAAc;IACd,IAAI;IACJ,QAAQ;IACR,IAAI;IACJ,IAAI;IACJ,SAAS;IACT,OAAO;IACP,QAAQ;IACR,YAAY;CACJ,CAAC;AAIX,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAU,CAAC;AAI3C,+DAA+D;AAC/D,iEAAiE;AACjE,mEAAmE;AACnE,qEAAqE;AACrE,MAAM,uBAAuB,GAA6D;IACxF,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,CAAC;IAClG,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC;IACpF,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,CAAC;IAC9C,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,CAAC;CACnE,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,SAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3F,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,EAAY,EAAE,IAAmB;IACtE,OAAO,uBAAuB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAmB;IACvD,OAAO,uBAAuB,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;AAC7C,CAAC;AAED,+EAA+E;AAC/E,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,yEAAyE;AACzE,+CAA+C;AAE/C,yEAAyE;AACzE,sEAAsE;AACtE,4EAA4E;AAC5E,mEAAmE;AACnE,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B,mEAAmE;AACnE,MAAM,WAAW,GAAG,KAAK,CAAC;AAE1B,wEAAwE;AACxE,4EAA4E;AAC5E,gDAAgD;AAChD,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAY1C,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAoB,EAAE,cAAuB;IAC7E,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAEvC,4EAA4E;IAC5E,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,cAAc,KAAK,SAAS,IAAI,cAAc,KAAK,IAAI,CAAC;IACjE,CAAC;IACD,IAAI,QAAQ,KAAK,YAAY,EAAE,CAAC;QAC9B,OAAO,cAAc,KAAK,SAAS,IAAI,cAAc,KAAK,IAAI,CAAC;IACjE,CAAC;IAED,sEAAsE;IACtE,IAAI,cAAc,KAAK,SAAS,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAC5D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,IAAI;YACP,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,cAAc,CAAC;QAE3D,KAAK,KAAK;YACR,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,cAAc,CAAC;QAE3D,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YACtC,OAAO,MAAM,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5D,CAAC;QAED,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YACtC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,CAAC;QAED,KAAK,IAAI,CAAC,CAAC,CAAC;YACV,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,WAAW;gBAAE,OAAO,KAAK,CAAC;YACrE,OAAO,MAAM,CAAC,QAAQ,CAAC,cAAgC,CAAC,CAAC;QAC3D,CAAC;QAED,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,mEAAmE;YACnE,IAAI,MAAM,CAAC,MAAM,GAAG,WAAW;gBAAE,OAAO,KAAK,CAAC;YAC9C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAgC,CAAC,CAAC;QAC5D,CAAC;QAED,KAAK,IAAI,CAAC,CAAC,CAAC;YACV,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YACtC,MAAM,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;YACjC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5B,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC;YACrD,OAAO,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;QAED,KAAK,IAAI,CAAC,CAAC,CAAC;YACV,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YACtC,MAAM,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;YACjC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5B,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC;YACrD,OAAO,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;QAED,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC;YACpC,MAAM,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;YACjC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5B,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5B,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC;YACxE,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAC1C,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,CAAC;QAED,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YACtC,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;YACrC,IAAI,KAAK,CAAC,MAAM,GAAG,eAAe;gBAAE,OAAO,KAAK,CAAC;YACjD,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBACzC,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,yDAAyD;gBACzD,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO,CAAC,CAAC,CAAC;YACR,kEAAkE;YAClE,mEAAmE;YACnE,yDAAyD;YACzD,MAAM,WAAW,GAAU,QAAQ,CAAC;YACpC,KAAK,WAAW,CAAC;YACjB,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;AACH,CAAC;AAYD;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAoC,EACpC,iBAA0D,EAAE;IAE5D,MAAM,MAAM,GAAsB,EAAE,CAAC;IAErC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC1B,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,MAAM,CAAC,IAAI,CAAC;gBACV,cAAc,EAAE,CAAC;gBACjB,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,QAAQ,EAAE,CAAC,CAAC,QAAoB;gBAChC,OAAO,EAAE,qBAAqB,CAAC,CAAC,QAAQ,uBAAuB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;aACvF,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,qCAAqC;QACrC,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;YACnB,KAAK,SAAS;gBACZ,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC1B,MAAM,CAAC,IAAI,CAAC;wBACV,cAAc,EAAE,CAAC;wBACjB,SAAS,EAAE,CAAC,CAAC,SAAS;wBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;wBACpB,OAAO,EAAE,qDAAqD,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG;qBACjF,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM;YACR,KAAK,IAAI,CAAC;YACV,KAAK,QAAQ;gBACX,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC1B,MAAM,CAAC,IAAI,CAAC;wBACV,cAAc,EAAE,CAAC;wBACjB,SAAS,EAAE,CAAC,CAAC,SAAS;wBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;wBACpB,OAAO,EAAE,aAAa,CAAC,CAAC,QAAQ,8BAA8B;qBAC/D,CAAC,CAAC;gBACL,CAAC;qBAAM,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;oBACzC,MAAM,CAAC,IAAI,CAAC;wBACV,cAAc,EAAE,CAAC;wBACjB,SAAS,EAAE,CAAC,CAAC,SAAS;wBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;wBACpB,OAAO,EAAE,aAAa,CAAC,CAAC,QAAQ,sBAAsB,WAAW,gBAAgB,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG;qBACpG,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM;YACR,KAAK,QAAQ,CAAC;YACd,KAAK,YAAY;gBACf,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC1B,MAAM,CAAC,IAAI,CAAC;wBACV,cAAc,EAAE,CAAC;wBACjB,SAAS,EAAE,CAAC,CAAC,SAAS;wBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;wBACpB,OAAO,EAAE,aAAa,CAAC,CAAC,QAAQ,0BAA0B,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG;qBAC7E,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM;YACR,KAAK,OAAO;gBACV,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC1B,MAAM,CAAC,IAAI,CAAC;wBACV,cAAc,EAAE,CAAC;wBACjB,SAAS,EAAE,CAAC,CAAC,SAAS;wBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;wBACpB,OAAO,EAAE,kDAAkD,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG;qBAC9E,CAAC,CAAC;gBACL,CAAC;qBAAM,CAAC;oBACN,IAAI,CAAC;wBACH,6DAA6D;wBAC7D,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC5C,CAAC;oBAAC,OAAO,CAAC,EAAE,CAAC;wBACX,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;wBACvD,MAAM,CAAC,IAAI,CAAC;4BACV,cAAc,EAAE,CAAC;4BACjB,SAAS,EAAE,CAAC,CAAC,SAAS;4BACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;4BACpB,OAAO,EAAE,0BAA0B,GAAG,EAAE;yBACzC,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;gBACD,MAAM;YACR;gBACE,+CAA+C;gBAC/C,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC1B,MAAM,CAAC,IAAI,CAAC;wBACV,cAAc,EAAE,CAAC;wBACjB,SAAS,EAAE,CAAC,CAAC,SAAS;wBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;wBACpB,OAAO,EAAE,aAAa,CAAC,CAAC,QAAQ,mCAAmC,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG;qBACtF,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM;QACV,CAAC;QAED,2EAA2E;QAC3E,MAAM,IAAI,GAAG,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,IAAI,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;YACtD,MAAM,CAAC,IAAI,CAAC;gBACV,cAAc,EAAE,CAAC;gBACjB,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,OAAO,EAAE,aAAa,CAAC,CAAC,QAAQ,oCAAoC,CAAC,CAAC,SAAS,aAAa,IAAI,yBAAyB,IAAI,KAAK,qBAAqB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;aAC5K,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/flags/propagation.d.ts

@@ -0,0 +1,16 @@
+import type { EvalContext } from './evaluator.js';
+/** Canonical HTTP header carrying the serialized eval context. */
+export declare const BRIDGE_CONTEXT_HEADER: "x-bridge-context";
+/** Serialize an eval context into a base64url-encoded JSON string. */
+export declare function serializeContext(ctx: EvalContext): string;
+/**
+ * Parse the header value back into an EvalContext. Returns `undefined` if the
+ * value is missing, malformed, or carries an unknown wire version. Callers
+ * should treat undefined as "no context shipped" — never throw on the request
+ * path.
+ */
+export declare function deserializeContext(headerValue: string | undefined | null): EvalContext | undefined;
+export declare function serverInstanceId(): string;
+/** Test-only — reset the cached server-instance id. */
+export declare function __resetServerInstanceId(): void;
+//# sourceMappingURL=propagation.d.ts.map

package/dist/flags/propagation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.d.ts","sourceRoot":"","sources":["../../src/flags/propagation.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAOlD,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,EAAG,kBAA2B,CAAC;AAWjE,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAMzD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,WAAW,GAAG,SAAS,CAoBlG;AAcD,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAED,uDAAuD;AACvD,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/dist/flags/propagation.js

@@ -0,0 +1,107 @@
+// Frontend → backend context propagation (TBP-171).
+//
+// The frontend SDK serializes the eval context into a header on outgoing
+// HTTP requests; the backend SDK / NestJS guard / Express middleware reads
+// the same header and rehydrates the context for backend evals. Same flag,
+// same answer, on both ends of the wire.
+//
+// Header name + format are part of the SDK ↔ backend contract — don't
+// change without a coordinated rollout.
+import { generateAnonymousId } from './identity.js';
+/** Canonical HTTP header carrying the serialized eval context. */
+export const BRIDGE_CONTEXT_HEADER = 'x-bridge-context';
+/** Wire format version — bump when the JSON shape changes incompatibly. */
+const WIRE_VERSION = 1;
+/** Serialize an eval context into a base64url-encoded JSON string. */
+export function serializeContext(ctx) {
+    const wire = { v: WIRE_VERSION };
+    if (ctx.identity)
+        wire.i = ctx.identity;
+    // Omit empty attributes object — keep the wire small.
+    if (ctx.attributes && Object.keys(ctx.attributes).length > 0)
+        wire.a = ctx.attributes;
+    return base64UrlEncode(JSON.stringify(wire));
+}
+/**
+ * Parse the header value back into an EvalContext. Returns `undefined` if the
+ * value is missing, malformed, or carries an unknown wire version. Callers
+ * should treat undefined as "no context shipped" — never throw on the request
+ * path.
+ */
+export function deserializeContext(headerValue) {
+    if (typeof headerValue !== 'string' || headerValue.length === 0)
+        return undefined;
+    let json;
+    try {
+        json = base64UrlDecode(headerValue);
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return undefined;
+    if (parsed.v !== WIRE_VERSION)
+        return undefined;
+    return {
+        identity: typeof parsed.i === 'string' ? parsed.i : undefined,
+        attributes: parsed.a && typeof parsed.a === 'object' ? { ...parsed.a } : {},
+    };
+}
+/**
+ * Generate a stable per-process server-instance ID for backend SDKs that
+ * want to evaluate system-level flags (TBP-172). The first call mints a UUID
+ * v4; subsequent calls return the same value for the lifetime of the process.
+ *
+ * The ID is INTENTIONALLY ephemeral across restarts — system flags should
+ * target either a small set of stable identifiers (region, version, role) or
+ * a hash of those, not the auto-generated process ID. The process ID is
+ * primarily for telemetry / debugging where "which server replied to me"
+ * matters.
+ */
+let _serverInstanceId;
+export function serverInstanceId() {
+    if (!_serverInstanceId) {
+        _serverInstanceId = `srv_${generateAnonymousId().replace(/^anon_/, '')}`;
+    }
+    return _serverInstanceId;
+}
+/** Test-only — reset the cached server-instance id. */
+export function __resetServerInstanceId() {
+    _serverInstanceId = undefined;
+}
+// ── base64url helpers (no dep on Buffer; works in browser + node) ───────────
+function base64UrlEncode(input) {
+    // Use globalThis.btoa when available (browsers, modern Node), fall back to Buffer.
+    const g = globalThis;
+    let b64;
+    if (typeof g.btoa === 'function') {
+        // btoa handles binary strings — convert UTF-8 to binary string first
+        b64 = g.btoa(unescape(encodeURIComponent(input)));
+    }
+    else if (typeof Buffer !== 'undefined') {
+        b64 = Buffer.from(input, 'utf-8').toString('base64');
+    }
+    else {
+        throw new Error('No base64 encoder available');
+    }
+    return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64UrlDecode(input) {
+    const padded = input.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (input.length % 4)) % 4);
+    const g = globalThis;
+    if (typeof g.atob === 'function') {
+        return decodeURIComponent(escape(g.atob(padded)));
+    }
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(padded, 'base64').toString('utf-8');
+    }
+    throw new Error('No base64 decoder available');
+}
+//# sourceMappingURL=propagation.js.map

package/dist/flags/propagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.js","sourceRoot":"","sources":["../../src/flags/propagation.ts"],"names":[],"mappings":"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"}