├── CONTRIBUTING.md ├── LICENSE └── README.md /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to EOSIO Manifest Specification 2 | 3 | Interested in contributing? That's awesome! Here are some guidelines to get started quickly and easily: 4 | 5 | - [Reporting An Issue](#reporting-an-issue) 6 | - [Bug Reports](#bug-reports) 7 | - [Feature Requests](#feature-requests) 8 | - [Change Requests](#change-requests) 9 | - [Working on EOSIO Manifest Specification](#working-on-eosio-manifest-specification) 10 | - [Feature Branches](#feature-branches) 11 | - [Submitting Pull Requests](#submitting-pull-requests) 12 | - [Testing and Quality Assurance](#testing-and-quality-assurance) 13 | - [Conduct](#conduct) 14 | - [Contributor License & Acknowledgments](#contributor-license--acknowledgments) 15 | - [References](#references) 16 | 17 | ## Reporting An Issue 18 | 19 | If you're about to raise an issue because you think you've found a problem with EOSIO Manifest Specification, or you'd like to make a request for a new feature in the codebase, or any other reason… please read this first. 20 | 21 | The GitHub issue tracker is the preferred channel for [bug reports](#bug-reports), [feature requests](#feature-requests), and [submitting pull requests](#submitting-pull-requests), but please respect the following restrictions: 22 | 23 | * Please **search for existing issues**. Help us keep duplicate issues to a minimum by checking to see if someone has already reported your problem or requested your idea. 24 | 25 | * Please **be civil**. Keep the discussion on topic and respect the opinions of others. See also our [Contributor Code of Conduct](#conduct). 26 | 27 | ### Bug Reports 28 | 29 | A bug is a _demonstrable problem_ that is caused by the code in the repository. Good bug reports are extremely helpful - thank you! 30 | 31 | Guidelines for bug reports: 32 | 33 | 1. **Use the GitHub issue search** — check if the issue has already been 34 | reported. 35 | 36 | 1. **Check if the issue has been fixed** — look for [closed issues in the 37 | current milestone](https://github.com/EOSIO/manifest-spec/issues?q=is%3Aissue+is%3Aclosed) or try to reproduce it 38 | using the latest `develop` branch. 39 | 40 | A good bug report shouldn't leave others needing to chase you up for more information. Be sure to include the details of your environment and relevant tests that demonstrate the failure. 41 | 42 | [Report a bug](https://github.com/EOSIO/manifest-spec/issues/new?title=Bug%3A) 43 | 44 | ### Feature Requests 45 | 46 | Feature requests are welcome. Before you submit one be sure to have: 47 | 48 | 1. **Use the GitHub search** and check the feature hasn't already been requested. 49 | 1. Take a moment to think about whether your idea fits with the scope and aims of the project. 50 | 1. Remember, it's up to *you* to make a strong case to convince the project's leaders of the merits of this feature. Please provide as much detail and context as possible, this means explaining the use case and why it is likely to be common. 51 | 52 | ### Change Requests 53 | 54 | Change requests cover both architectural and functional changes to how EOSIO Manifest Specification works. If you have an idea for a new or different dependency, a refactor, or an improvement to a feature, etc - please be sure to: 55 | 56 | 1. **Use the GitHub search** and check someone else didn't get there first 57 | 1. Take a moment to think about the best way to make a case for, and explain what you're thinking. Are you sure this shouldn't really be a [bug report](#bug-reports) or a [feature request](#feature-requests)? Is it really one idea or is it many? What's the context? What problem are you solving? Why is what you are suggesting better than what's already there? 58 | 59 | ## Working on EOSIO Manifest Specification 60 | 61 | Contributions are welcome and encouraged! If you are looking for a good place to start, check out the [good first issue](https://github.com/EOSIO/manifest-spec/labels/good%20first%20issue) label in GitHub issues. 62 | 63 | Also, please follow these guidelines when submitting code: 64 | 65 | ### Feature Branches 66 | 67 | To get it out of the way: 68 | 69 | - **[develop](https://github.com/EOSIO/manifest-spec/tree/develop)** is the development branch. All work on the next release happens here so you should generally branch off `develop`. Do **NOT** use this branch for a production site. 70 | - **[master](https://github.com/EOSIO/manifest-spec)** contains the latest release of manifest-specification. This branch may be used in production. Do **NOT** use this branch to work on manifest-specification's source. 71 | 72 | ### Submitting Pull Requests 73 | 74 | Pull requests are awesome. If you're looking to raise a PR for something which doesn't have an open issue, please think carefully about [raising an issue](#reporting-an-issue) which your PR can close, especially if you're fixing a bug. This makes it more likely that there will be enough information available for your PR to be properly tested and merged. 75 | 76 | ### Testing and Quality Assurance 77 | 78 | Never underestimate just how useful quality assurance is. If you're looking to get involved with the code base and don't know where to start, checking out and testing a pull request is one of the most useful things you could do. 79 | 80 | Essentially, [check out the latest develop branch](#working-on-manifest-specification), take it for a spin, and if you find anything odd, please follow the [bug report guidelines](#bug-reports) and let us know! 81 | 82 | ## Conduct 83 | 84 | While contributing, please be respectful and constructive, so that participation in our project is a positive experience for everyone. 85 | 86 | Examples of behavior that contributes to creating a positive environment include: 87 | - Using welcoming and inclusive language 88 | - Being respectful of differing viewpoints and experiences 89 | - Gracefully accepting constructive criticism 90 | - Focusing on what is best for the community 91 | - Showing empathy towards other community members 92 | 93 | Examples of unacceptable behavior include: 94 | - The use of sexualized language or imagery and unwelcome sexual attention or advances 95 | - Trolling, insulting/derogatory comments, and personal or political attacks 96 | - Public or private harassment 97 | - Publishing others’ private information, such as a physical or electronic address, without explicit permission 98 | - Other conduct which could reasonably be considered inappropriate in a professional setting 99 | 100 | ## Contributor License & Acknowledgments 101 | 102 | Whenever you make a contribution to this project, you license your contribution under the same terms as set out in LICENSE, and you represent and warrant that you have the right to license your contribution under those terms. Whenever you make a contribution to this project, you also certify in the terms of the Developer’s Certificate of Origin set out below: 103 | 104 | ``` 105 | Developer Certificate of Origin 106 | Version 1.1 107 | 108 | Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 109 | 1 Letterman Drive 110 | Suite D4700 111 | San Francisco, CA, 94129 112 | 113 | Everyone is permitted to copy and distribute verbatim copies of this 114 | license document, but changing it is not allowed. 115 | 116 | 117 | Developer's Certificate of Origin 1.1 118 | 119 | By making a contribution to this project, I certify that: 120 | 121 | (a) The contribution was created in whole or in part by me and I 122 | have the right to submit it under the open source license 123 | indicated in the file; or 124 | 125 | (b) The contribution is based upon previous work that, to the best 126 | of my knowledge, is covered under an appropriate open source 127 | license and I have the right under that license to submit that 128 | work with modifications, whether created in whole or in part 129 | by me, under the same open source license (unless I am 130 | permitted to submit under a different license), as indicated 131 | in the file; or 132 | 133 | (c) The contribution was provided directly to me by some other 134 | person who certified (a), (b) or (c) and I have not modified 135 | it. 136 | 137 | (d) I understand and agree that this project and the contribution 138 | are public and that a record of the contribution (including all 139 | personal information I submit with it, including my sign-off) is 140 | maintained indefinitely and may be redistributed consistent with 141 | this project or the open source license(s) involved. 142 | ``` 143 | 144 | ## References 145 | 146 | * Overall CONTRIB adapted from https://github.com/mathjax/MathJax/blob/master/CONTRIBUTING.md 147 | * Conduct section adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 148 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2017-2019 block.one and its contributors. All rights reserved. 2 | 3 | The MIT License 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in 13 | all copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | THE SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # EOSIO Manifest Specification 2 | [![EOSIO Labs](https://img.shields.io/badge/EOSIO-Labs-5cb3ff.svg)](#about-eosio-labs) 3 | 4 | **Specification Version**: 0.7.0 5 | 6 | A specification for metadata describing integrating apps, and the actions they can request from a user. This specification can be used by wallets to provide more information about the app a user is interacting with, and to run transaction pre-flight security checks comparing the contents of a transaction request with what integrating apps have declared about themselves. 7 | 8 | ## Related Reading 9 | 10 | This is just one of several thought leadership pieces focusing on wallets, key management and authentication, and the relating user experience. For more context and related reading, check out these these pieces: 11 | 12 | * [A Passwordless Future: Building Towards More Secure and Usable Authentication Systems](https://medium.com/eosio/a-passwordless-future-building-towards-more-secure-and-usable-authentication-systems-e188f07e4b87) 13 | * [EOSIO Labs™ Release: The Universal Authenticator Library (UAL) — Increasing the Accessibility of Blockchain Applications](https://medium.com/eosio/eosio-labs-release-the-universal-authenticator-library-ual-increasing-the-accessibility-of-8e2bd62a78a5) 14 | * [EOSIO Software Release: Ricardian Contract Specifications and the Ricardian Template Toolkit](https://medium.com/eosio/eosio-software-release-ricardian-contract-specifications-and-the-ricardian-template-toolkit-a0db787429d1) 15 | * [EOSIO Authentication Transport Protocol Specification](https://github.com/EOSIO/eosio-authentication-transport-protocol-spec) 16 | 17 | ## About EOSIO Labs 18 | 19 | EOSIO Labs repositories are experimental. Developers in the community are encouraged to use EOSIO Labs repositories as the basis for code and concepts to incorporate into their applications. Community members are also welcome to contribute and further develop these repositories. Since these repositories are not supported by Block.one, we may not provide responses to issue reports, pull requests, updates to functionality, or other requests from the community, and we encourage the community to take responsibility for these. 20 | 21 | ## Why an Application Manifest? 22 | 1. Provides user agents metadata about the app for use in application listings (history, favorites, app directories, etc.) 23 | 1. Provides app developers with a way to declare which contract actions on a given chain an application on their domain is able to propose to end users 24 | 1. Allows user agents to run various transaction pre-flight security assertions comparing the contents of a transaction request with what apps have declared about themselves 25 | 1. Provides end users with more security and a better sense of trust--information about the apps they're using is displayed consistently and the transactions themselves are secured with on-chain assertions 26 | 27 | ## Application Requirements for EOSIO User Agent Compatibility 28 | * The application must register an [application manifest](#application-manifest-specification) on each chain it wishes to transact on. 29 | * Developers must have publicly-accessible `chain-manifests.json` and `app-metadata.json` files. 30 | * The `chain-manifests.json` file must be at the root of the application's declared domain or subdomain. 31 | 32 | ### How It Works 33 | 1. In order for an EOSIO-enabled application to be compatible with EOSIO user agents, developers must submit an [app manifest](#application-manifest-specification) to the EOSIO chains on which it wishes to push transactions. 34 | 1. When the application makes a request or proposes a transaction, it must pass along a `declaredDomain`. The user agent will verify the following items. If any fails verification, an error will be displayed to the user or returned to the application. It will verify: 35 | * that the domain is hosting a `chain-manifests.json` file and that all manifests listed reference the declared domain and app metadata consistently; 36 | * that the domain is hosting a `app-metadata.json` file and that it contains all required fields; 37 | * that the domain in the provided manifest matches the domain submitting the transaction (applicable only to web applications); 38 | * that the application's identifier (bundle ID, package name, etc.) as reported by the OS is whitelisted by the metadata's `appIdentifiers` field (applicable only to native applications); 39 | * that the contract action(s) in the transaction are whitelisted in the manifest; 40 | * that the hash of the icon in `app-metadata.json` matches the checksum of the icon file itself; 41 | * that the hash of `app-metadata.json` matches the hash declared in the provided manifest; 42 | 1. When the user accepts the transaction, the user agent will hash the manifest and add an [assertion action](https://github.com/EOSIO/eosio.assert) to the transaction so that the chain can validate that the manifest provided to the user agent has been registered for the given domain on that chain. If the manifest's hash is not found on the chain, the chain may reject the transaction. 43 | 44 | ## Specification Versioning 45 | 46 | Both the application metadata and chain manifest files defined below include fields defining the version of the manifest specification that they follow. Version numbers follow a semantic versioning (semver) inspired scheme consisting of three integers separated by periods `.` and represent the Major, Minor, and Patch levels in the form `M.m.p`. For example `1.2.3`. 47 | 48 | Fields are interpretted as follows: 49 | 50 | * **Patch**: Minor changes that only affect the textual description of the specification with no functional changes to schema, generation, or verification. Updates to non-functional parts of the schema like `title` or `description` fields are permitted. 51 | * **Minor**: Backward-compatible changes to the spec and schema. This would include changes such as adding _optional_ fields or loosening of requirements. A manifest based on spec x.y **MUST** be verifiable against spec x.z where y < z. 52 | * **Major**: Backward-incompatible changes to the spec and schema. This would include changes such as adding new _required_ fields or tightening of requirements. A manifest based on spec x._ is **NOT** required to be verifiable against spec y._ where x < y. 53 | 54 | ## Application Metadata Specification 55 | Application metadata must be declared in a publicly available JSON file. The location of this file, along with its checksum hash, will be referenced by the EOSIO chain(s). Having this file referenced on-chain enables EOSIO-compatible user agents to validate the integrity of the metadata and may provide other future benefits. For example, developers could look for these records on the chain and put together public directories of EOSIO-compatible applications. 56 | 57 | All of the following fields are required with the exception of `description`, `sslfingerprint`, and `appIdentifiers`. 58 | 59 | ### Metadata Fields 60 | * `spec_version`: The specification version as described in [Specification Versioning](#specification-versioning). 61 | * `name`: The full name of the application. This will be user-facing in app listings, history, etc. 62 | * `shortname`: A shorter name for the application. 63 | * `scope`: An absolute path relative to the application's root. (`/` or `/app`, but not `../`) 64 | * `apphome`: Tells the browser where your application should start when it is launched. This must fall within the scope. 65 | * `icon`: An HTTPS url or absolute path relative to the application's root followed by a SHA-256 checksum hash. May be displayed in app listings, history, favorites, etc. (`https://landeos.io/icon.png#SHA256HASH` or `/icon.png#SHA256HASH`, but not `../icon.png#SHA256HASH`) 66 | * `appIdentifiers`: Optional. For native applications, an array of whitelisted app identifiers. (e.g., bundle identifiers for iOS apps, package names for Android apps) 67 | * `description`: Optional. A paragraph about your application. May be displayed in app listings, etc. 68 | * `sslfingerprint`: Optional. Your app domain's SSL SHA-256 fingerprint as a hex string. If present, the user agent may check that the SSL fingerprint of the domain submitting the transaction matches that in the provided manifest. 69 | * `chains`: An array containing the `chainId`, `chainName`, and `icon` for any chain for which your application plans to require signing. User agents will use this for presenting a friendly chain name and icon to the user when prompted for signing. 70 | 71 | **Note:** While the icon specification is still being developed, for now, these should be PNGs or JPGs at 256px x 256px. 72 | 73 | ### Example 74 | ```json 75 | { 76 | "spec_version": "0.7.0", 77 | "name": "Landeos Property Registry", 78 | "shortname": "Landeos", 79 | "scope": "/", 80 | "apphome": "/home", 81 | "icon": "https://landeos.io/icon.png#SHA256HASH", 82 | "appIdentifiers": ["io.landeos.registry"], 83 | "description": "Landeos is a decentralized property registry...", 84 | "sslfingerprint": "E1 3F 0E 03 2D 05 3C D2 81 FB 57 02 42 51 D0 44 32 08 35 58 8C 73 C4 44 83 4D CA 3E 71 15 16 20", 85 | "chains": [ 86 | { 87 | "chainId": "EOSIO1111", 88 | "chainName": "Property Chain", 89 | "icon": "/propertyChain.png#SHA256HASH" 90 | }, 91 | { 92 | "chainId": "EOSIO2222", 93 | "chainName": "Other Chain", 94 | "icon": "/otherChain.png#SHA256HASH" 95 | } 96 | ] 97 | } 98 | ``` 99 | 100 | This specification will be extended later to include additional application metadata (e.g., app screenshots and other listing-related data.) 101 | 102 | ## Application Manifest Specification 103 | Manifests must be registered using the `eosio.assert::add.manifest` action on every chain on which your app will transact. (See: https://github.com/EOSIO/eosio.assert.) Furthermore, an array of chain manifests must be declared in a publicly available JSON file at the root of the application's `declaredDomain`. 104 | 105 | ### Manifest Fields 106 | * `account`: The chain account name. This is the account that registered the application manifest. 107 | * `domain`: The uri or bundle identifier. 108 | * `appmeta`: The publicly-accessible location of the application metadata JSON file and its hash. Must be an absolute path. 109 | * `whitelist`: An array containing the `contract` and `action` for each allowed contract action(s) that your app can propose. 110 | * The `contract` and/or `action` fields within the `whitelist` on the manifest may contain a wildcard. Wildcards are denoted by `""` (empty string). For example, the manifest below whitelists all `eosio.token` actions and another specific contract action. 111 | 112 | ```javascript 113 | { 114 | account: string, 115 | domain: string, 116 | appmeta: string, 117 | whitelist: contract_action[] 118 | } 119 | ``` 120 | 121 | **contract_action** 122 | ```javascript 123 | { 124 | contract: string, 125 | action: string 126 | }, 127 | ``` 128 | 129 | ### Example 130 | ```json 131 | { 132 | "account": "landeospropr", 133 | "domain": "https://landeos.io", 134 | "appmeta": "https://landeos.io/app-metadata.json#SHA256HASH", 135 | "whitelist": [ 136 | { 137 | "contract": "eosio.token", 138 | "action": "" 139 | }, 140 | { 141 | "contract": "landeospropr", 142 | "action": "register" 143 | } 144 | ] 145 | } 146 | ``` 147 | 148 | ### chain-manifests.json 149 | This file must reside at the root of your application's declared domain. Consists of a top-level object of two properties: 150 | 151 | * `spec_version`: The specification version as described in [Specification Versioning](#specification-versioning). 152 | * `manifests`: An array of objects, each of which has two properties: 153 | * `chainId`: The ID of a chain with which the application will transact. 154 | * `manifest`: A manifest as described above in [Application Manifest Specification](#application-manifest-specification). 155 | 156 | Here's an example: 157 | 158 | ```json 159 | { 160 | "spec_version": "0.0.7", 161 | "manifests": [ 162 | { 163 | "chainId": "EOSIO1111", 164 | "manifest": { 165 | "account": "landeospropr", 166 | "domain": "https://landeos.io", 167 | "appmeta": "https://landeos.io/app-metadata.json#SHA256HASH", 168 | "whitelist": [ 169 | { 170 | "contract": "eosio.token", 171 | "action": "" 172 | }, 173 | { 174 | "contract": "landeospropr", 175 | "action": "register" 176 | } 177 | ] 178 | } 179 | }, 180 | { 181 | "chainId": "EOSIO2222", 182 | "manifest": { 183 | "account": "landeospropr", 184 | "domain": "https://landeos.io", 185 | "appmeta": "https://landeos.io/app-metadata.json#SHA256HASH", 186 | "whitelist": [ 187 | { 188 | "contract": "eosio.token", 189 | "action": "" 190 | }, 191 | { 192 | "contract": "landeospropr", 193 | "action": "register" 194 | } 195 | ] 196 | } 197 | } 198 | ] 199 | } 200 | ``` 201 | 202 | ## Contributing 203 | 204 | [Contributing Guide](./CONTRIBUTING.md) 205 | 206 | [Code of Conduct](./CONTRIBUTING.md#conduct) 207 | 208 | ## License 209 | 210 | [MIT](./LICENSE) 211 | 212 | ## Important 213 | 214 | See LICENSE for copyright and license terms. Block.one makes its contribution on a voluntary basis as a member of the EOSIO community and is not responsible for ensuring the overall performance of the software or any related applications. We make no representation, warranty, guarantee or undertaking in respect of the software or any related documentation, whether expressed or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall we 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 documentation or the use or other dealings in the software or documentation. Any test results or performance figures are indicative and will not reflect performance under all conditions. Any reference to any third party or third-party product, service or other resource is not an endorsement or recommendation by Block.one. We are not responsible, and disclaim any and all responsibility and liability, for your use of or reliance on any of these resources. Third-party resources may be updated, changed or terminated at any time, so the information here may be out of date or inaccurate. Any person using or offering this software in connection with providing software, goods or services to third parties shall advise such third parties of these license terms, disclaimers and exclusions of liability. Block.one, EOSIO, EOSIO Labs, EOS, the heptahedron and associated logos are trademarks of Block.one. 215 | 216 | Wallets and related components are complex software that require the highest levels of security. If incorrectly built or used, they may compromise users’ private keys and digital assets. Wallet applications and related components should undergo thorough security evaluations before being used. Only experienced developers should work with this software. 217 | --------------------------------------------------------------------------------