Web of Things (WoT) Scripting API

1. Run validate an ExposedThingInit on init. If that fails, throw SyntaxError and stop.
2. Let td be the result of running clone given init.
3. For each scheme in td.["securityDefinitions"], make a request to the underlying platform to check if it is supported by at least one Protocol Binding. If not, then remove scheme from td.
4. If td.["security"] does not exist in td.["securityDefinitions"], then remove security from td.
5. For each affordance in td.properties, td.actions and td.events, run the following sub-steps:
   1. For each form in affordance.forms:
      1. If form.contentType is not recognized by the runtime as valid remove contentType from form.
      2. If form.href has an unknown schema, remove href from form.
      3. If form.href is absolute and its authority it is not recognized by the runtime as valid, remove href from form.
      4. If form.href is already in use by other ExposedThings, remove href from form.
6. Search for missing required properties in td accordingly to TD JSON Schema.
   Editor's note

   The editors find this step vague. It will be improved or removed in the next iteration.

7. For each missing property run these sub-steps:
   1. If missing is title generate a runtime unique name and assign to title.
   2. If missing is @context assign the latest supported Thing Description context URI.
   3. If missing is instance assign the string 1.0.0.
   4. If missing is forms generate a list of Forms using the available Protocol Bindings and content types encoders. Then assign the obtained list to forms.
   5. If missing is security assign the label of the first supported SecurityScheme in securityDefinitions field. If no SecurityScheme is found generate a NoSecurityScheme called nosec and assign the string nosec to security.
      Issue 1

      The discussion about how to properly generate a value for security is still open. See issue #299

   6. If missing is href define formStub as the partial Form that does not have href. Generate a valid url using the first Protocol Binding that satisfy the requirements of formStub. Assign url to href. If not Protocol Binding can be found remove formStub from td.
   7. Add missing to td with value as value
8. Run validate a TD on td. If that fails re-throw the error and stop
9. Return td

1. Parse TD JSON Schema and load it in object called exposedThingInitSchema
2. let optional be a list containing the following strings: title, @context, instance, forms, security, and href.
3. For each property and sub-property key in exposedThingInitSchema equals to required execute the following steps:
   1. if key value is an Array then remove all its elements equal to the elements in optional
   2. if key value is a string then if value is equal to one of the elements in optional remove key from exposedThingInitSchema
4. Return the result of validating an object with JSON Schema given init and exposedThingInitSchema.
   Editor's note

   The validating an object with JSON Schema steps are still under discussion. Currently this specification reference to the validation process of JSONSchema. Please follow this document when validating init with exposedThingInitSchema. Notice that the working group is evaluating an alternative formal approach.

1. Return a Promise promise and execute the next steps in parallel.
2. If this.[[value]] is not undefined, resolve promise with that value and stop.
3. If this.data is not a ReadableStream or if dataUsed is true, or if form is not an object or if schema or its type are null or undefined, then reject promise with NotReadableError and stop.
4. If form.contentType is not application/json and if a mapping is not available in the Protocol Bindings from form.contentType to [JSON-SCHEMA], reject promise with NotSupportedError and stop.
5. Let reader be the result of getting a reader from data. If that threw an exception, reject promise with that exception and stop.
6. Let bytes be the result of reading all bytes from data with reader.
7. Set dataUsed to true.
8. If form.contentType is not application/json and if a mapping is available in the Protocol Bindings from form.contentType to [JSON-SCHEMA], transform bytes with that mapping.
9. Let json be the result of running parse JSON from bytes on bytes. If that throws, reject promise with that exception and stop.
10. Set [[value]] to the result of running check data schema on json and schema. If that throws, reject promise with that exception and stop.
11. Resolve promise with [[value]].

1. Return a Promise promise and execute the next steps in parallel.
2. If data is not ReadableStream or if dataUsed is true, reject promise with NotReadableError and stop.
3. Let reader be the result of getting a reader from data. If that threw an exception, reject promise with that exception and stop.
4. Let bytes be the result of reading all bytes from data with reader.
5. Set dataUsed to true.
6. Let arrayBuffer be a new ArrayBuffer whose contents are bytes. If that throws, reject promise with that exception and stop.
7. Resolve promise with arrayBuffer.

1. Let type be schema.type.
2. If type is "null" and if payload is not null, throw TypeError and stop, otherwise return null.
3. If type is "boolean" and payload is a falsy value or its byte length is 0, return false, otherwise return true.
4. If type is "integer" or "number",
   1. If payload is not a number, throw TypeError and stop.
   2. If form.minimum is defined and payload is smaller, or if form.maximum is defined and payload is bigger, throw a RangeError and stop.
5. If type is "string", return payload.
6. If type is "array", run these sub-steps:
   1. If payload is not an array, throw TypeError and stop.
   2. If form.minItems is defined and payload.length is less than that, or if form.maxItems is defined and payload.length is more than that, throw RangeError and stop.
   3. Let payload be an array of items obtained by running the check data schema steps on each element item of payload and schema.items. If this throws at any stage, re-throw that exception and stop.
7. If type is "object", run these sub-steps:
   1. If payload or schema.properties is not an object, throw TypeError and stop.
   2. For each key in payload:
      1. Let prop be payload[key].
      2. Let propSchema be interaction.properties[key].
      3. Let prop be the result of running the check data schema steps on prop and propSchema. If this throws, re-throw that exception and stop.
   3. Let required be schema.required if that is an array or an empty array otherwise.
   4. For each key in required, if key is not present in payload, throw SyntaxError and stop.
8. Return payload.

1. Let idata be a new an InteractionOutput object.
2. Set idata.form to form, set idata.schema to schema, set |idata.data to null and set idata.[[value]] to undefined.
3. If source is a ReadableStream object, let idata.data be source, return idata and stop.
4. If schema and its type are defined and not null, run these sub-steps:
   1. If type is "null" and source is not "null", throw TypeError and stop.
   2. If type is "boolean" and source is a falsy value, set idata.[[value]] to false, otherwise set it to true.
   3. If type is "integer" or "number" and source is not a number, or if form.minimum is defined and source is smaller, or if form.maximum is defined and source is bigger, throw RangeError and stop.
   4. If type is "string" and source is not a string, let idata.[[value]] be the result of running serialize JSON to bytes given source. If that is failure, throw SyntaxError and stop.
   5. If type is "array", run these sub-steps:
      1. If source is not an array, throw a TypeError and stop.
      2. Let length be the length of source.
      3. If form.minItems is defined and length is less than that, or if form.maxItems is defined and length is more than that, throw RangeError and stop.
      4. For each item in source, let itemschema be schema.items and let item be the result of running the create interaction request steps given item, form and itemschema. If this throws, re-throw that exception and stop.
      5. Set data.[[value]] to source.
   6. If type is "object", run these sub-steps:
      1. If source is not an object, throw TypeError and stop.
      2. If schema.properties is not an object, throw TypeError and stop.
      3. For each key in source,
         1. Let value be source[key].
         2. Let propschema be properties.interactions[key].
         3. Let value be the result of running the create interaction request steps on value, form and propschema. If this throws, re-throw that exception and stop.
      4. If schema.required is an array, for each item in required check if item is a property name in source. If an item is not found in source, throw SyntaxError and stop.
      5. Set data.[[value]] to source.
5. Set idata.data to a new ReadableStream created from idata.[[value]] internal slot as its underlying source.
6. Return idata.

1. Let result be a new InteractionOutput object.
2. Let result.schema be schema.
3. Let result.form be form.
4. Let result.data be a new ReadableStream with the payload data of response as its underlying source.
5. Let result.dataUsed be false.
6. Return result.

Stops delivering notifications for the subscription. It takes an optional parameter options and returns a Promise. When invoked, the method MUST execute the following steps:

1. Return a Promise promise and execute the next steps in parallel.
2. If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
3. If options' formIndex is defined, let unsubscribeForm be the Form associated with formIndex in [[interaction]]'s forms array.
4. Otherwise let unsubscribeForm be the result of running the find a matching unsubscribe form algorithm given [[form]].
5. If unsubscribeForm is failure, reject promise with a SyntaxError and stop.
6. If [[type]] is "property", make a request to the underlying platform via the Protocol Bindings to stop observing the Property identified by [[name]] with unsubscribeForm and optional URI templates given in options' uriVariables.
7. Otherwise, if [[type]] is "event", make a request to the underlying platform via the Protocol Bindings to unsubscribe from the Event identified by [[name]] with unsubscribeForm, with optional URI templates given in options' uriVariables and optional unsubscribe data given in options.data.
8. If the request fails, reject promise with the error received from the Protocol Bindings and stop.
9. Otherwise:
   • set active to false.
   • if [[type]] is "event", remove [[name]] from [[thing]].[[activeSubscriptions]] .
   • if [[type]] is "property", remove [[name]] from [[thing]].[[activeObservations]] .
   • Resolve promise.
10. If the underlying platform receives further notifications for this subscription, implementations SHOULD silently suppress them.

1. Let results be an empty array.
2. For each form in [[interaction]].forms,
   1. Add an internal slot [[matchLevel]] on form and set its value to 0.
   2. If form.op is "unobserveproperty" if [[type]] is "property" or if form.op is "unsubscribeevent" if [[type]] is"event",
      1. Set the internal slot [[matchLevel]] on form to 1 and add form to results.
      2. If form.href and [[subscribeForm]].href are same origin-domain, increment form.[[matchLevel]].
      3. If form.contentType is equal to [[subscribeForm]]'s contentType and form.[[matchLevel]] is greater than 2, increment form.[[matchLevel]].
3. If results is empty, return null and terminate these steps.
4. Return the first form in results that has the highest [[matchLevel]] value.

A typical way to compromise any process is to send it a corrupted input via one of the exposed interfaces. This can be done to a script instance using WoT interface it exposes.

Mitigation:

Implementors of this API SHOULD perform validation on all script inputs. In addition to input validation, fuzzing should be used to verify that the input processing is done correctly. There are many tools and techniques in existence to do such validation. More details can be found in [WOT-SECURITY].

In case a script is compromised or misbehaving, the underlying physical device (and potentially surrounded environment) can be damaged if a script can use directly exposed native device interfaces. If such interfaces lack safety checks on their inputs, they might bring the underlying physical device (or environment) to an unsafe state (i.e. device overheats and explodes).

Mitigation:

The WoT Scripting Runtime SHOULD avoid directly exposing the native device interfaces to the script developers. Instead, a WoT Scripting Runtime should provide a hardware abstraction layer for accessing the native device interfaces. Such hardware abstraction layer should refuse to execute commands that might put the device (or environment) to an unsafe state. Additionally, in order to reduce the damage to a physical WoT device in cases a script gets compromised, it is important to minimize the number of interfaces that are exposed or accessible to a particular script based on its functionality.

If the WoT Scripting Runtime supports post-manufacturing provisioning or updates of scripts, WoT Scripting Runtime or any related data (including security credentials), it can be a major attack vector. An attacker can try to modify any above described element during the update or provisioning process or simply provision attacker's code and data directly.

Mitigation:

Post-manufacturing provisioning or update of scripts, WoT Scripting Runtime or any related data should be done in a secure fashion. A set of recommendations for secure update and post-manufacturing provisioning can be found in [WOT-SECURITY].

Typically the WoT Scripting Runtime needs to store the security credentials that are provisioned to a WoT device to operate in WoT network. If an attacker can compromise the confidentiality or integrity of these credentials, then it can obtain access to the WoT assets, impersonate WoT things or devices or create Denial-Of-Service (DoS) attacks.

Mitigation:

The WoT Scripting Runtime should securely store the provisioned security credentials, guaranteeing their integrity and confidentiality. In case there are more than one tenant on a single WoT-enabled device, a WoT Scripting Runtime should guarantee isolation of each tenant provisioned security credentials. Additionally, in order to minimize a risk that provisioned security credentials get compromised, the WoT Scripting Runtime should not expose any API for scripts to query the provisioned security credentials.