@atlasprivacy/consent-sdk 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,155 @@
+# Changelog
+
+## 1.0.0 (unreleased)
+
+First public release, published to npm as `@atlasprivacy/consent-sdk` under the MIT license. The internal builds listed below were never released; their changes are all part of 1.0.0.
+
+- Synchronize saved decisions across tabs and SDK instances, reconcile server choices, and expose `onPreferenceChange` and `atlas-consent:change` without credentials.
+- Display every configured purpose when notice sections are incomplete, and reject malformed notice structures before mounting.
+- Keep dialogs dismissible during saves and rendering failures. Use native modality for dynamically added page content and restore focus through nested Shadow DOM.
+- Allow a cancelled launch to be reopened immediately; ignore stale session responses and form callbacks.
+- Sanitize notice HTML with bundled DOMPurify and support enforcing Trusted Types without a permissive default policy.
+- Preserve HTTP status on invalid JSON responses. Add `refresh()` and a reload action for notices changed while editing.
+- Test Chromium, Firefox, WebKit, and mobile viewports; gate CI packages on dependency auditing; reject changed assets at existing published versions.
+
+## Internal builds before 1.0.0
+
+These versions were built for testing only and are superseded by 1.0.0.
+
+### Internal 1.8.0
+
+- Render the consent form inside the SDK, in the website's page, in Shadow DOM. Websites no longer load an Atlas iframe. The Atlas API is unchanged and still stores every decision.
+- Make all session, decision, and view calls from the SDK. Save failures now report the real error code and HTTP status through `onError`.
+- Remove the `frame_timeout` and `result_mismatch` error codes. An invalid save result now reports `invalid_response`.
+- Keep `ui.html` and `atlas-consent-ui.js` only for the Atlas dashboard preview.
+- Keep one session, and so one consent record, when the notice, its language or the website list changes. Sessions renew on use and last a year from last use once they hold a consent. `getClaim()` keeps working across these changes.
+- Name the main button by what it saves: "Accept Necessary" when no optional purpose is ticked, "Accept Selected" when any is. It previously could read "Accept Necessary" while saving optional purposes.
+- Show notice text as written: names keep their case, and paragraphs, lists, emphasis and links are kept.
+- Mark purposes, collected data and shared data with their own language when it differs from the notice language.
+- `open()` on a mounted panel scrolls the panel into view instead of doing nothing.
+- Report every failure to `onError` and `atlas-consent:error` once, including failures of `mount()` and `open()`. Errors use the specific `code` Atlas now sends, such as `consent_linked` and `notice_changed`.
+- `theme: "dark"` uses dark colours unless colours are set. Unknown theme values fall back to light.
+- Script tags accept `data-auto-show` and `data-appearance`, use the script's own Atlas address before the build default, report `missing_container` for a panel without `data-target`, and fire `atlas-consent:ready` after the configuration loads.
+- Send the SDK version with each save, for the audit trail.
+- CI publishes `shipping` packages as well as `dev` and `staging`; the 1.7.0 note that shipping stays disabled no longer applies.
+
+### Internal 1.7.1
+
+- Send the save operation's key in the `Idempotency-Key` header, the same name the Atlas API uses, instead of `submission_id` in the body. Requires a backend that allows this header.
+
+### Internal 1.7.0
+
+- Select build-time backend defaults from DEV_URL, STAGING_URL, and PRODUCTION_URL. Explicit API URLs still override the default.
+- Publish dev and staging packages to the private GitLab Generic Package Registry after checks pass. Keep shipping publication disabled.
+- Expire all pipeline artifacts after one week.
+- Use the ci-cogserver runner, fresh checkouts, and npm caches outside the source directory.
+
+### Internal 1.6.2
+
+- Remove the docs directory and package references.
+- Cancel automatic startup when the client is closed before configuration loads.
+- Scope saved preferences by backend base URL and app ID. Old app-only preferences require a fresh choice.
+- Validate configuration, session choices, and saved results before use. Report invalid notice rendering.
+- Preserve browser initialization in consumer bundles.
+- Keep Shift+Tab inside the dialog from its initial focus position.
+- Choose button text by contrast and handle non-string appearance overrides safely.
+
+### Internal 1.6.1
+
+- Separate client lifecycle, storage, transport, dialog accessibility, protocol, and hosted UI modules.
+- Separate UI styles, theme handling, rendering, and session API calls.
+- Group tests by unit, integration, browser, dashboard, package, and fixtures.
+- Add formatting, lint, import-boundary, and package-consumer checks to the GitLab build.
+- Clean generated output before each build. Preserve public exports and asset filenames.
+
+### Internal 1.6.0
+
+- Add System theme. The form follows device light and dark preferences and updates when they change. Brand color stays the same.
+
+### Internal 1.5.5
+
+- Cancel pending form launches on close. Reject calls after destroy before sending requests.
+- Restore page access when two clients open dialogs. Open panel clients in a popup when `open()` is called.
+- Close dialogs after completion even when the completion callback throws.
+- Time out form reads and saves after 15 seconds. Keep the submission ID for retries.
+- Disable editable choices during a save. Keep required choices selected.
+- Validate appearance keys and support IPv6 localhost base URLs.
+- Add GitLab build, browser test, and package jobs with distributable artifacts.
+- Verify asset version and integrity before backend sync. Build before package creation.
+
+### Internal 1.5.4
+
+- Fix: group tick boxes were cleared after every save.
+- Fix: opening a popup or full page no longer puts a focus ring on the close button. Tab still reaches it first.
+- Script-tag start now reports a clear error when the script address does not contain `/consent-sdk/assets/`, instead of calling a wrong address.
+- The build fails if the SDK version in `src/protocol.ts` differs from `package.json`.
+- Requests time out after 15 seconds. A panel that never loads now reports `frame_timeout`, like the popup.
+- A mismatched or unexpected completion message now raises `onError` (`result_mismatch`) instead of being ignored.
+- `onClose` runs only when a form was open, and not on `destroy()`.
+- The page behind a popup or full-page form is inert while it is open, and restored on close.
+- Saved preferences in storage are checked before use.
+
+### Internal 1.5.3
+
+- Embedded panel fills its container, with no grey side bands, and uses a calmer 14px text size.
+
+### Internal 1.5.2
+
+- Spacing now changes the whole form: text size, gaps, row padding and button height. Compact is clearly tighter.
+- The rounded font uses a humanist stack that looks different from Sans on every device.
+
+### Internal 1.5.1
+
+- Fix: colors and style passed in code were replaced by the saved look once the form loaded.
+
+### Internal 1.5.0
+
+- Full page mode opens over the same page instead of a new browser tab, and closes back to it. Show full-page consent in the current tab. Restore website scrolling and focus on close.
+
+### Internal 1.4.0
+
+- Match the consent screen used in templates and levels: bordered group cards with a chevron, a tick box per group and per purpose, "+N more" data summaries, a shared-data list, a fade above stacked footer buttons, and the same type sizes.
+- Match its corner size by default. The "soft" corners are 6px.
+- Skip the link section, as the template screen does.
+
+### Internal 1.3.1
+
+- Show the three buttons in one row when the form is wide.
+- Remove the in-form preview banner. The dashboard already says nothing is saved.
+
+### Internal 1.3.0
+
+- Add the `appearance` option. Colors and style set in code override the look saved in Atlas.
+
+### Internal 1.2.3
+
+- Default to the FRS theme: pink `#ae0a60` and text `#1a202c`, the same colors as the consent level screen.
+
+### Internal 1.2.2
+
+- Do not move focus into the form in dashboard previews.
+
+### Internal 1.2.1
+
+- Do not move focus or scroll when an embedded panel opens.
+
+### Internal 1.2.0
+
+- Render the consent form from the consent level: title, sections, data groups and button names.
+- Add collapsible data groups, pinned buttons and "Accept Selected" after a choice is changed.
+- Remove text and button label settings from appearance. They now come from the consent level.
+
+### Internal 1.1.0
+
+- Add appearance settings from the dashboard: theme, colors, corner style, font, density, brand label, text and button labels.
+- Apply appearance with CSS variables. The SDK accepts hex colors and fixed choices only.
+- Add a live `appearance` message so the dashboard preview updates while a person edits.
+- Report one anonymous "form shown" count per opened form, for the dashboard funnel.
+- Appearance changes do not change the consent version, so saved choices stay valid.
+
+### Internal 1.0.0
+
+- Add panel, automatic popup and button-opened full page modes.
+- Add scoped anonymous sessions, saved choices and verified backend linking.
+- Add shared hosted UI, TypeScript types, lifecycle methods and completion events.
+- Add versioned browser/ESM bundles and asset integrity manifest.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FRS Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+# Atlas Consent SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A browser SDK with a built-in consent form and three display modes: embedded panel, automatic popup, and full page opened by a button. The form runs in your page. Atlas provides the API that loads the notice and stores decisions.
+
+In Atlas, open **Consents → Integrations**, create an app and select a published consent level. Open the integration to add your website origins and enable it. You can create multiple apps for the same level. Copy the app ID and API base URL from its setup guide. Keep your organization API token on your server.
+
+## Add the SDK
+
+Load the script from jsDelivr, or use the versioned asset URL from your Atlas deployment. Pin an exact version; a version URL never changes. Replace the version and app ID below. See [npm](https://www.npmjs.com/package/@atlasprivacy/consent-sdk?activeTab=versions) for the current version.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@atlasprivacy/consent-sdk@1.0.0/dist/atlas-consent.js"></script>
+```
+
+With a bundler, install the package and import it:
+
+```sh
+npm install @atlasprivacy/consent-sdk
+```
+
+```ts
+import { create } from "@atlasprivacy/consent-sdk";
+```
+
+The SDK talks to the production Atlas API by default. To use another Atlas deployment, pass `apiBaseUrl` to `create()` or set `data-api-base-url` on the script tag. A script loaded from an Atlas deployment uses that deployment by default.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@atlasprivacy/consent-sdk@1.0.0/dist/atlas-consent.js"></script>
+<script>
+  const consent = AtlasConsent.create({
+    appId: "ac_app_REPLACE_WITH_YOUR_APP_ID",
+    mode: "popup",
+    onComplete(result, claim) {
+      console.log(result.choices);
+      // Send claim to your authenticated backend when the visitor logs in.
+    },
+    onError(error) {
+      console.error(error.code, error.message);
+    },
+  });
+</script>
+```
+
+An `apiBaseUrl` must include any deployment path prefix. Do not add `/api/v1` or `/consent-sdk` to it. API URLs are public; do not put secrets in them.
+
+For a script-only automatic popup:
+
+```html
+<script
+  defer
+  src="https://cdn.jsdelivr.net/npm/@atlasprivacy/consent-sdk@1.0.0/dist/atlas-consent.js"
+  data-atlas-app="ac_app_REPLACE_WITH_YOUR_APP_ID"
+  data-mode="popup"
+></script>
+```
+
+Script tag attributes:
+
+| Attribute           | Meaning                                                                 |
+| ------------------- | ----------------------------------------------------------------------- |
+| `data-atlas-app`    | Required. The app ID.                                                   |
+| `data-mode`         | `panel`, `popup` or `page`. Defaults to the mode saved in Atlas.        |
+| `data-target`       | CSS selector of the panel container. Required when the mode is `panel`. |
+| `data-language`     | Notice language. Defaults to `en`.                                      |
+| `data-auto-show`    | `false` stops a popup from opening by itself.                           |
+| `data-appearance`   | The `appearance` object as JSON, for example `'{"theme":"dark"}'`.      |
+| `data-api-base-url` | The Atlas API base URL. Defaults as described above.                    |
+
+`window` receives `atlas-consent:ready` once the configuration has loaded, with the client in `event.detail.client`. If the mode is `panel` and there is no `data-target`, the SDK reports a `missing_container` error instead of showing nothing. Use either automatic initialization or `create()`, so you do not create duplicate instances.
+
+## Choose a display mode
+
+### Embedded panel
+
+Place the container before initialization. The SDK inserts the form into this element.
+
+```html
+<div id="consent-panel"></div>
+<script>
+  const consent = AtlasConsent.create({
+    appId: "ac_app_REPLACE_WITH_YOUR_APP_ID",
+    mode: "panel",
+    target: "#consent-panel",
+  });
+</script>
+```
+
+### Popup on page load
+
+Use `mode: 'popup'`. The SDK opens it when there is no current saved choice for this app and configuration. To open only on demand, set `autoShow: false` and call `consent.open()` from your button.
+
+### Full page on a button click
+
+```js
+const consent = AtlasConsent.create({
+  appId: "ac_app_REPLACE_WITH_YOUR_APP_ID",
+  mode: "page",
+});
+document.querySelector("#privacy-choice").addEventListener("click", () => {
+  consent.open().catch(console.error);
+});
+```
+
+`open()` shows a full-screen consent page over your current page, so the visitor never leaves your site, and returns to it when done.
+
+## Read and change a choice
+
+```js
+await consent.ready;
+const preference = consent.getPreference(); // null until a current choice is saved
+const claim = consent.getClaim(); // scoped proof; keep private
+await consent.open(); // show the form again
+consent.close(); // close the UI
+await consent.refresh(); // reload the notice and session, keeping an embedded panel in its container
+consent.destroy(); // remove the form, listeners and pending requests
+```
+
+`open()` opens the form as a dialog. Panel clients use the popup layout for it. If a panel is already mounted, `open()` scrolls it into view and focuses it instead of opening a second form.
+
+`ready` resolves to the published configuration. `onComplete(result, claim)` runs after a successful save. Results include `ref_id`, `app_id`, `level_id`, `config_version`, and a purpose-ID-to-boolean `choices` map. Necessary purposes stay selected. Saves use the existing Atlas consent history and audit services.
+
+Use `onPreferenceChange(preference)` to update optional processing when the SDK observes a changed choice, including a withdrawal in another tab. It receives a preference snapshot or `null` when no current consent exists. It also reports an initially stored choice after configuration loads. The equivalent window event is `atlas-consent:change`, with `{ appId, preference }` in `event.detail`; it contains no session or claim token. `onComplete` remains specific to saves from this instance's active form.
+
+Clients synchronize choices through local storage, including multiple SDK instances in the same page. A form with stale choices is closed when another instance or tab changes its saved decision; reopen it to edit the latest choice. Clearing storage invalidates the cached preference. Direct storage edits in the same document are noticed on the next preference or claim read. When storage is blocked, clients retain their own choices in memory for that page only.
+
+Session reads reconcile cached choices with the server. Choices from an older notice are kept for editing and claiming, but do not count as consent to a new notice. A `notice_changed` save error provides a **Reload consent form** action, which fetches the current notice before another save. Code integrations can also call `refresh()`.
+
+Every configured purpose is displayed, even when the notice omits a purpose group or section. Malformed notice structures are rejected before mounting. Rendering errors retain a dismissal control, and saving leaves Close available. Closing an in-flight save dismisses the form; it does not undo a decision the server may already have recorded.
+
+The main button saves exactly the boxes that are ticked. Its name follows them: the level's "Accept Necessary" text when no optional purpose is ticked, and its "Accept Selected" text when any is.
+
+Use `appearance` to set colors and style in code: `appearance: { theme: 'light', primary_color: '#ae0a60', background_color: '#ffffff', text_color: '#1a202c', radius: 'soft', font: 'system', density: 'comfortable' }`. Values in code override the look saved in Atlas. Colors must be 6-digit hex values; anything else falls back to the default. Wording and button names always come from the consent level, shown as written, with the notice's paragraphs, lists, emphasis and links.
+
+`theme` is `light`, `dark` or `system`. `dark` uses a dark background and light text unless you set your own colors. `system` follows the device's light or dark preference and updates when it changes. Both keep your brand color.
+
+Use `language: 'en'` (default), or a language supported by the configured level. The notice's title, sections and buttons follow that language. Atlas keeps purposes, collected data and shared data in one language (English), so those lists are marked with their own `lang` for screen readers. The SDK's few own labels, such as "Your choices are saved.", are English.
+
+## Link a verified customer
+
+A browser can save anonymously. Page loads create no consent record; the first decision creates one. A reference ID alone does not authorize access or prove identity.
+
+After your application verifies the customer, send `consent.getClaim()` to your own authenticated backend. Your backend must choose the verified customer ID from its login session, not trust a customer ID supplied by the browser. Then call:
+
+```http
+POST /api/v1/consents/records/{ref_id}/claim
+Authorization: Bearer YOUR_ORGANIZATION_API_TOKEN
+Content-Type: application/json
+
+{
+  "app_id": "ac_app_REPLACE_WITH_YOUR_APP_ID",
+  "claim_token": "THE_BROWSER_CLAIM_TOKEN",
+  "customer_id": "YOUR_VERIFIED_ID"
+}
+```
+
+You can also supply verified applicant email/mobile fields supported by the applicant API. The token needs `consents.records.applicant.update`. Claiming preserves the anonymous evidence, writes the link to the record's audit trail, and ends browser access to the record. A repeat claim for the same customer is safe; a conflicting customer is rejected. If the customer already has a record on this consent's system, the claim returns 409 and the anonymous record stays unlinked. The error names the existing record, so your backend can save the website choices there with `PUT /api/v1/consents/records/{ref_id}/decisions`. Provide a verified customer flow for later changes after linking. The anonymous SDK cannot read a customer's other records.
+
+The claim keeps working when the notice, its language or your website list changes, because the browser keeps the same session and the same record. After linking, opening the form in that browser reports `consent_linked`; send the visitor to your signed-in flow.
+
+## Storage and cookie integrations
+
+The SDK stores a backend-and-app-specific session capability and choices in your website's local storage. It sets no cookies. If storage is unavailable, the UI still works but cannot remember a choice after reload.
+
+A browser session that never saved a choice lasts 30 days. Once it holds a consent, it lasts a year from its last use. Opening the form renews it, and so does a page load in its last 60 days. A changed notice or language asks the visitor again, with their earlier choices ticked, and saves to the same record. Stored consent evidence remains in Atlas after a session ends. Clearing browser storage, or a session ending, loses the anonymous proof: the next save creates a new record. Treat the claim token as a credential: do not put it in URLs, analytics, logs, or third-party scripts.
+
+The popup is a consent form. It does **not** scan cookies or automatically block scripts, trackers, tags, or server-side processing. Your site must keep optional processing disabled until the matching purpose choice is true, and stop it when the visitor changes that choice. Map purpose IDs explicitly. `getPreference()` is a browser convenience, not authorization for backend access.
+
+## Origins and errors
+
+Register exact origins, including scheme and non-default port. `https://example.com` and `https://www.example.com` are separate. Wildcards and paths are rejected. HTTP is supported only for local development origins. Deploy the API and assets over HTTPS.
+
+Errors are `ConsentError` objects with `code`, `message`, and HTTP `status` (0 when no response arrived). Every failure goes to `onError` and to the `atlas-consent:error` event on `window`, once. `ready`, `open()`, and `mount()` also reject with it.
+
+| Code                                                                             | Meaning                                                                  |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `session_invalid`                                                                | The session expired or is unknown. The SDK starts a new one by itself.   |
+| `consent_linked`                                                                 | This browser's consent is linked to a customer. Use your signed-in flow. |
+| `notice_changed`                                                                 | The notice changed while the form was open. Open the form again.         |
+| `not_allowed`                                                                    | This website's origin is not allowed, or the integration is disabled.    |
+| `not_found`                                                                      | Unknown app ID.                                                          |
+| `invalid_request`, `request_too_large`, `conflict`                               | Atlas rejected the request.                                              |
+| `rate_limited`                                                                   | HTTP 429. Wait before trying again.                                      |
+| `service_unavailable`, `internal_error`                                          | HTTP 503 or 500. Try again later.                                        |
+| `request_timeout`, `network_error`, `invalid_response`                           | Atlas did not answer, or answered with something unusable.               |
+| `invalid_app`, `invalid_api_base_url`, `invalid_appearance`, `missing_container` | Integration mistakes on your page.                                       |
+| `form_error`                                                                     | The notice could not be drawn.                                           |
+| `destroyed`                                                                      | The client was destroyed. Not reported to `onError`.                     |
+| `consent_sdk_error`                                                              | Sent by Atlas backends older than this SDK, in place of the codes above. |
+
+Do not automatically retry writes without a delay. The form keeps the same `Idempotency-Key` when retrying a failed save, so a retry cannot save twice.
+
+## Security notes
+
+- Session and claim tokens are kept in the visitor's `localStorage` under `atlas-consent:v2:<encoded-api-base-url>:<appId>`, so they are readable by any script on your site. Keep third-party scripts on pages that use the SDK to a minimum and use a Content Security Policy.
+- The consent form runs in your page, in Shadow DOM. Shadow DOM keeps your CSS and the form's CSS apart. It is not a security boundary: any script on your page can read or change the form, so what Atlas records is what your page submitted. Keep third-party scripts off pages that collect consent.
+- Allow your Atlas API host in your Content Security Policy `connect-src`. The form needs no inline style permission.
+- Notice HTML is sanitized with bundled DOMPurify, then rebuilt using the SDK's restricted formatting and link rules. On sites enforcing Trusted Types, allow the `dompurify` policy name in `trusted-types`; for example, `require-trusted-types-for 'script'; trusted-types dompurify`. No permissive default policy is needed. A CSP that disallows the sanitizer policy fails closed and leaves the dialog dismissible.
+- Atlas writes each save to the record's audit trail with how it arrived: the kind of form (drawn on your website, the older Atlas-hosted form, or no browser origin at all), the SDK version the browser reported, your website's origin, the session, the notice version and language, and the caller's IP address, with a hash of those details. Treat a save as what your page sent, not as proof of what the person saw.
+
+## Browser support
+
+The SDK targets current evergreen Chrome/Edge, Firefox, and Safari, using native modal dialogs and Shadow DOM. Automated tests cover Chromium, Firefox, WebKit, and mobile Chromium/WebKit viewports. Mobile projects emulate browser devices; they do not replace testing on physical phones or embedded webviews. Destroy an instance when a framework component unmounts; create a new instance when it mounts again. The ESM entry point can be imported during server rendering, but `create()` must run in the browser.
+
+The package contains the script and ESM builds, TypeScript declarations, and `dist/manifest.json` with SHA-384 hashes for Subresource Integrity.
+
+## License
+
+MIT

package/dist/DOMPurify-LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed 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.