selenium-webdriver 4.46.0 → 4.48.0

package/bidi/serialization/record.js

@@ -0,0 +1,345 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+const { register, resolve } = require('./registry')
+
+class ValidationError extends Error {}
+
+// Validates a *present* value against a resolved type node, and returns the value to
+// assign for it — usually the same value, but for a nested ref-to-record/union parsed
+// inbound (fromWire()/build() results, not the raw wire object) and for list/map/inline
+// record values (a fresh, deeply-frozen copy, so validity can't be corrupted after the
+// fact by mutating an array or object a caller still holds a reference to).
+// Outbound nested refs deliberately keep the caller's own value instead of the
+// newly-constructed instance — the nested `new referenced.RecordClass(value)` /
+// `referenced.build(value)` call below exists only to validate, matching the
+// constructor's existing outbound behavior of trusting the caller's own object shape.
+// `direction` only affects how a nested ref-to-record/union is itself validated/parsed.
+function validateValue(typeNode, value, path, direction) {
+  if (value === null) {
+    // `primitive: 'null'` (project_bidi_schema.mjs's projectRef(), for a type whose
+    // every alternative was null) means null itself is the valid value — accept it
+    // even though `nullable` (a *different* value also being permitted alongside a
+    // non-null base type) wasn't separately set.
+    if (typeNode.nullable || typeNode.primitive === 'null') return null
+    throw new ValidationError(`${path}: null is not allowed`)
+  }
+
+  if (typeNode.primitive !== undefined) {
+    // A present, non-null value never satisfies a `primitive: 'null'` node — value
+    // being null is the only thing the branch above would have already returned for.
+    if (typeNode.primitive === 'null') {
+      throw new ValidationError(`${path}: expected null, got ${typeof value}`)
+    }
+    const expected = { string: 'string', integer: 'number', number: 'number', boolean: 'boolean' }[typeNode.primitive]
+    if (expected && typeof value !== expected) {
+      throw new ValidationError(`${path}: expected ${typeNode.primitive}, got ${typeof value}`)
+    }
+    // JSON has no representation for NaN/±Infinity — reject them for both numeric
+    // primitives before the integer-specific check narrows further. (Number.isInteger
+    // already excludes them too, so this is only load-bearing for a bare `number`.)
+    if ((typeNode.primitive === 'integer' || typeNode.primitive === 'number') && !Number.isFinite(value)) {
+      throw new ValidationError(`${path}: expected a finite ${typeNode.primitive}, got ${value}`)
+    }
+    // `number` admits any JSON number; `integer` rejects a fractional value
+    // (5.7) while still accepting one written 5.0 (Number.isInteger(5.0) is true).
+    if (typeNode.primitive === 'integer' && !Number.isInteger(value)) {
+      throw new ValidationError(`${path}: expected an integer, got ${value}`)
+    }
+    // An inline literal choice (project_bidi_schema.mjs's enumNode()) carries both
+    // `primitive` and `enum` — the primitive check above narrows the type, but the
+    // closed vocabulary below still needs to run, so only return early when there
+    // is no `enum` to fall through to.
+    if (typeNode.enum === undefined) return value
+  }
+
+  if (typeNode.const !== undefined) {
+    if (value !== typeNode.const) {
+      throw new ValidationError(
+        `${path}: expected constant ${JSON.stringify(typeNode.const)}, got ${JSON.stringify(value)}`,
+      )
+    }
+    return value
+  }
+
+  if (typeNode.enum !== undefined) {
+    if (!typeNode.enum.includes(value)) {
+      throw new ValidationError(
+        `${path}: "${value}" is not a valid value; expected one of: ${typeNode.enum.join(', ')}`,
+      )
+    }
+    return value
+  }
+
+  if (typeNode.list !== undefined) {
+    if (!Array.isArray(value)) {
+      throw new ValidationError(`${path}: expected a list, got ${typeof value}`)
+    }
+    return Object.freeze(value.map((item, i) => validateValue(typeNode.list, item, `${path}[${i}]`, direction)))
+  }
+
+  if (typeNode.map !== undefined) {
+    if (typeof value !== 'object' || Array.isArray(value) || value === null) {
+      throw new ValidationError(`${path}: expected an object, got ${typeof value}`)
+    }
+    // Object.create(null), not `{}`: `key` is wire-controlled and a literal "__proto__"
+    // entry assigned via bracket notation would hijack result's prototype instead of
+    // becoming a data property (CWE-1321) — a null-prototype object has no such trap.
+    const result = Object.create(null)
+    for (const [key, entry] of Object.entries(value)) {
+      result[key] = validateValue(typeNode.map, entry, `${path}.${key}`, direction)
+    }
+    return Object.freeze(result)
+  }
+
+  if (typeNode.ref !== undefined) {
+    const referenced = resolve(typeNode.ref)
+    if (referenced === undefined) return value // not yet registered — best-effort, skip deep validation
+
+    if (referenced.kind === 'enum') {
+      if (!referenced.includes(value)) {
+        throw new ValidationError(
+          `${path}: "${value}" is not a valid ${typeNode.ref} value; expected one of: ${referenced.values.join(', ')}`,
+        )
+      }
+      return value
+    }
+
+    if (referenced.kind === 'record') {
+      if (value instanceof referenced.RecordClass) return value // already validated
+      if (typeof value !== 'object' || Array.isArray(value) || value === null) {
+        throw new ValidationError(`${path}: expected an object, got ${typeof value}`)
+      }
+      // Recurse through the same-direction path so a nested field gets the same
+      // tolerance (inbound) or strictness (outbound) as its parent. Inbound returns
+      // the parsed instance itself, so a typed parent record ends up with a typed
+      // nested value instead of the raw wire object; outbound only validates this
+      // way (the caller's own value is what gets kept, see the note above).
+      if (direction === 'inbound') {
+        return referenced.RecordClass.fromWire(value)
+      }
+      new referenced.RecordClass(value)
+      return value
+    }
+
+    if (referenced.kind === 'union') {
+      if (direction === 'inbound') {
+        return referenced.fromWire(value)
+      }
+      referenced.build(value)
+      return value
+    }
+
+    if (referenced.kind === 'alias') {
+      return validateValue(referenced.type, value, path, direction)
+    }
+
+    return value
+  }
+
+  if (typeNode.union !== undefined) {
+    const errors = []
+    for (const variant of typeNode.union) {
+      try {
+        return validateValue(variant, value, path, direction)
+      } catch (err) {
+        errors.push(err.message)
+      }
+    }
+    throw new ValidationError(`${path}: value did not match any variant (${errors.join('; ')})`)
+  }
+
+  // An inline (unnamed) record type node — project_bidi_schema.mjs's projectEntry()
+  // emits this for an anonymous CDDL group (e.g. a field typed as an inline `{ ... }`
+  // rather than a ref to a named, defineRecord()'d type) — same FieldSpec shape as a
+  // named record's `fields`, just with nowhere to register a class. Gets the same
+  // directional required/extra/nested-value handling a named record's constructor/
+  // fromWire gives its fields, just built inline instead of through a Record class.
+  if (typeNode.record !== undefined) {
+    if (typeof value !== 'object' || Array.isArray(value) || value === null) {
+      throw new ValidationError(`${path}: expected an object, got ${typeof value}`)
+    }
+    const byWire = new Map(typeNode.record.map((f) => [f.wire, f]))
+    const result = {}
+    for (const field of typeNode.record) {
+      if (!Object.hasOwn(value, field.wire)) {
+        if (field.required) {
+          throw new ValidationError(`${path}.${field.wire}: required field is missing`)
+        }
+        continue
+      }
+      result[field.name] = validateValue(field.type, value[field.wire], `${path}.${field.wire}`, direction)
+    }
+    for (const wireKey of Object.keys(value)) {
+      if (byWire.has(wireKey)) continue
+      // No `extensible` concept exists for an inline record (project_bidi_schema.mjs
+      // never sets it there) — undeclared keys get exactly the non-extensible named-
+      // record treatment: rejected outbound, dropped-with-a-warning inbound.
+      if (direction === 'inbound') {
+        process.emitWarning(`${path}: undeclared property "${wireKey}"`, 'BiDiSchemaWarning')
+      } else {
+        throw new ValidationError(`${path}: unknown property "${wireKey}"`)
+      }
+    }
+    return Object.freeze(result)
+  }
+
+  return value
+}
+
+/**
+ * Registers a schema `record` — a fixed set of named fields, each independently
+ * validated on the way out (constructor) and in (fromWire()).
+ * @param {string} name Schema type name, e.g. 'network.AddInterceptParameters'.
+ * @param {Array<{name: string, wire: string, required: boolean, type: object}>} fields
+ * @param {{extensible?: boolean}} [options]
+ * @returns {{new (data: object): object, fromWire: function(unknown): object}}
+ *   The generated Record class — `new Record(data)` validates and constructs
+ *   outbound, `Record.fromWire(payload)` validates and parses inbound.
+ */
+function defineRecord(name, fields, options = {}) {
+  const { extensible = false } = options
+  const byWire = new Map(fields.map((f) => [f.wire, f]))
+  // JS property name -> wire key, the inverse of byWire — lets toJSON() below map an
+  // outbound instance's own (JS-facing) properties back to the wire's declared names.
+  const byName = new Map(fields.map((f) => [f.name, f.wire]))
+
+  class Record {
+    // Outbound: strict. Any value that doesn't match its declared shape is an error here.
+    constructor(data) {
+      if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        throw new ValidationError(`${name}: expected an object`)
+      }
+
+      for (const field of fields) {
+        if (!Object.hasOwn(data, field.wire)) {
+          if (field.required) {
+            throw new ValidationError(`${name}.${field.wire}: required field is missing`)
+          }
+          continue
+        }
+        const value = data[field.wire]
+        this[field.name] = validateValue(field.type, value, `${name}.${field.wire}`, 'outbound')
+      }
+
+      for (const wireKey of Object.keys(data)) {
+        if (byWire.has(wireKey)) continue
+        if (!extensible) {
+          throw new ValidationError(`${name}: unknown property "${wireKey}"`)
+        }
+        // Object.defineProperty, not `this[wireKey] = ...`: wireKey is caller-supplied
+        // and a literal "__proto__" key assigned via bracket notation hijacks this
+        // instance's actual prototype instead of becoming a field (CWE-1321).
+        // defineProperty always creates a genuine own data property, regardless of name.
+        Object.defineProperty(this, wireKey, {
+          value: data[wireKey], // vendor extras reach the wire on an extensible type
+          enumerable: true,
+          writable: true,
+          configurable: true,
+        })
+      }
+
+      Object.freeze(this)
+    }
+
+    // Inbound: tolerant of undeclared properties, but a missing required field
+    // is rejected just like a structurally invalid value — omission used to be
+    // tolerated here, but that's no longer required.
+    // Bypasses the constructor above entirely — a single constructor enforcing
+    // both directions symmetrically would make tolerated undeclared-property
+    // retention impossible.
+    static fromWire(payload) {
+      if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        throw new ValidationError(`${name}: expected an object on the wire, got ${typeof payload}`)
+      }
+
+      const instance = Object.create(Record.prototype)
+
+      for (const field of fields) {
+        if (!Object.hasOwn(payload, field.wire)) {
+          if (field.required) {
+            throw new ValidationError(`${name}.${field.wire}: required field is missing`)
+          }
+          continue // left genuinely absent, optional field
+        }
+        const value = payload[field.wire]
+        // A present value's shape is never tolerated, inbound or outbound.
+        instance[field.name] = validateValue(field.type, value, `${name}.${field.wire}`, 'inbound')
+      }
+
+      for (const wireKey of Object.keys(payload)) {
+        if (byWire.has(wireKey)) continue
+        // An extensible type preserves an undeclared field silently — no narrower
+        // criterion than "extensible" itself (not, say, only fields that happen to be
+        // sendable back on some other type). A non-extensible type warns and drops it
+        // instead — the warning belongs only to the drop, not the retention.
+        if (extensible) {
+          // Object.defineProperty, not `instance[wireKey] = ...` — see the matching
+          // comment in the constructor above: a literal "__proto__" key from an
+          // untrusted wire payload must become a field, not swap the prototype (CWE-1321).
+          Object.defineProperty(instance, wireKey, {
+            value: payload[wireKey],
+            enumerable: true,
+            writable: true,
+            configurable: true,
+          })
+        } else {
+          process.emitWarning(`${name}: undeclared property "${wireKey}"`, 'BiDiSchemaWarning')
+        }
+      }
+
+      Object.freeze(instance)
+      return instance
+    }
+
+    // The JSON.stringify hook: an instance stores its fields under their JS-facing
+    // property names (this[field.name]), but the wire needs the spec's own key
+    // (field.wire) — the two differ whenever a generator picks an idiomatic JS name
+    // distinct from the raw spec key. Runs automatically wherever this instance is
+    // serialized (directly, or nested inside another value being stringified), so a
+    // caller never has to remember to call it.
+    toJSON() {
+      // Object.create(null), not `{}`: an extra's key is wire-controlled (extensible
+      // types preserve undeclared properties verbatim, see the constructor above), and
+      // a literal "__proto__" key assigned via bracket notation would hijack wire's
+      // prototype instead of becoming a data property (CWE-1321) — same hazard the
+      // constructor/fromWire already guard against for the instance itself.
+      const wire = Object.create(null)
+      for (const key of Object.keys(this)) {
+        wire[byName.get(key) ?? key] = this[key] // extras have no JS-name mapping — already wire-keyed
+      }
+      return wire
+    }
+  }
+
+  Object.defineProperty(Record, 'name', { value: name })
+  register(name, { kind: 'record', RecordClass: Record })
+  return Record
+}
+
+/**
+ * Registers a schema `alias` — a name with no fields of its own, just a
+ * pointer to another type node (e.g. `network.Intercept` aliasing a plain
+ * string). A ref to an alias validates through the aliased type node.
+ * @param {string} name
+ * @param {object} type The schema's `type` node this name aliases.
+ */
+function defineAlias(name, type) {
+  register(name, { kind: 'alias', type })
+}
+
+module.exports = { defineRecord, defineAlias, ValidationError }

package/bidi/serialization/registry.js

@@ -0,0 +1,34 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// Shared type registry: every generated type registers itself here by its
+// exact schema name (e.g. 'network.InterceptPhase'), so a field whose type is
+// a `ref` can look up what the referenced type actually is — without every
+// domain file needing to import every other domain file directly, and without
+// needing types defined in dependency order (resolution happens at validation
+// time, not at define time, so forward and circular refs both work).
+const types = new Map()
+
+function register(name, entry) {
+  types.set(name, entry)
+}
+
+function resolve(name) {
+  return types.get(name)
+}
+
+module.exports = { register, resolve }

package/bidi/serialization/union.js

@@ -0,0 +1,102 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+const { register, resolve } = require('./registry')
+const { ValidationError } = require('./record')
+
+// Resolves the variant ref a value/payload matches, per the schema's selector shape:
+//   { by, variants: [{value, ref}], default? } - discriminated: match `data[by]` against
+//     each variant's value.
+//   { ordered: [{ref, requires}] }              - structural: first variant whose `requires`
+//     keys are all present in `data`, in spec order.
+function selectVariant(selector, data, hasKey) {
+  if (selector.by) {
+    const tag = hasKey(data, selector.by) ? data[selector.by] : undefined
+    const match = selector.variants.find((v) => v.value === tag)
+    if (match) return match.ref
+    return selector.default
+  }
+  if (selector.ordered) {
+    for (const variant of selector.ordered) {
+      if (variant.requires.every((key) => hasKey(data, key))) return variant.ref
+    }
+    return undefined
+  }
+  return undefined // correlated: resolved by request id elsewhere, not from the payload
+}
+
+/**
+ * Registers a schema `union` — a value that may be any one of several variant
+ * record types, resolved by a discriminator field or by structural shape.
+ * @param {string} name Schema type name, e.g. 'session.ProxyConfiguration'.
+ * @param {object} selector The schema's `selector` node for this union.
+ * @param {{objectOnly?: boolean}} [options]
+ * @returns {{build: function(unknown): object, fromWire: function(unknown): object}}
+ *   The registered union — `build(data)` resolves and constructs the matching
+ *   variant outbound, `fromWire(payload)` resolves and parses it inbound.
+ */
+function defineUnion(name, selector, options = {}) {
+  const { objectOnly = false } = options
+
+  const union = {
+    kind: 'union',
+
+    // Outbound: resolve which variant `data` describes, then delegate to that
+    // variant's own (strict) constructor. A discriminated selector's `default`
+    // catch-all can itself resolve to another union — not just a record — e.g.
+    // LocalValue's untyped RemoteReference arm (see unionSelector() in
+    // project_bidi_schema.mjs) — so recurse through that union's own dispatch
+    // rather than assuming every resolved ref is a record.
+    build(data) {
+      if (objectOnly && (typeof data !== 'object' || data === null || Array.isArray(data))) {
+        throw new ValidationError(`${name}: expected an object`)
+      }
+      const ref = selectVariant(selector, data, (d, key) => Object.hasOwn(d, key))
+      if (ref === undefined) {
+        throw new ValidationError(`${name}: value does not match any known variant`)
+      }
+      const variant = resolve(ref)
+      if (variant.kind === 'union') {
+        return variant.build(data)
+      }
+      return new variant.RecordClass(data)
+    },
+
+    // Inbound: resolve which variant `payload` matches. An unresolvable payload is a
+    // closed-vocabulary miss — always an error, never a warning, since there is no
+    // valid typed object to fall back to. Same nested-union case as build() above.
+    fromWire(payload) {
+      if (objectOnly && (typeof payload !== 'object' || payload === null || Array.isArray(payload))) {
+        throw new ValidationError(`${name}: expected an object on the wire, got ${typeof payload}`)
+      }
+      const ref = selectVariant(selector, payload, (d, key) => Object.hasOwn(d, key))
+      if (ref === undefined) {
+        throw new ValidationError(`${name}: received a variant not in this binding's BiDi schema`)
+      }
+      const variant = resolve(ref)
+      if (variant.kind === 'union') {
+        return variant.fromWire(payload)
+      }
+      return variant.RecordClass.fromWire(payload)
+    },
+  }
+
+  register(name, union)
+  return union
+}
+
+module.exports = { defineUnion }