@dashevo/app-connect-contract 4.2.0-beta.4

package/.mocharc.yml

@@ -0,0 +1,2 @@
+require: test/bootstrap.js
+recursive: true

package/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "app-connect-contract"
+description = "App Connect data contract schema and tools. The wallet's encrypted response to an app login request"
+version.workspace = true
+edition = "2021"
+rust-version.workspace = true
+license = "MIT"
+
+[dependencies]
+thiserror = "2.0.12"
+platform-version = { path = "../rs-platform-version" }
+serde_json = { version = "1.0" }
+platform-value = { path = "../rs-platform-value" }
+[dev-dependencies]
+base58 = "0.2.0"

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Dash Core Group, Inc.
+
+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

@@ -0,0 +1,39 @@
+# App Connect Contract
+
+The App Connect system contract carries the wallet's encrypted response to an
+app login request. It activates at protocol version 14 and has the same ID on
+every network: `H8F9mP1BM55TE1ShsxPZHzhyinaMdY9bMmP85mkDhcJJ`.
+
+Its only document type is `loginKeyResponse`, written by the wallet's identity
+after the user approves:
+
+| Property | Bytes | Meaning |
+| --- | --- | --- |
+| `appEphemeralPubKeyHash` | 20 | `hash160` of the ephemeral public key in the app's request |
+| `walletEphemeralPubKey` | 33 | Compressed ephemeral public key used to derive the shared secret |
+| `encryptedPayload` | 60–572 | Encrypted granted private keys: 28-byte envelope plus 32 bytes per key, for 1–17 keys (session key plus up to eight bindings with both purposes) |
+
+All three properties are required. The contract checks their byte lengths;
+clients validate the public key, ciphertext framing and decrypted grant.
+
+The type is `indexOnly`, immutable and deletable. Its `byRequest` index is a
+flat composite terminal `(appEphemeralPubKeyHash, $ownerId)`. The wallet key and
+ciphertext are `entryPayload` values, so there is no primary document row or
+per-request tree. Each identity may answer a request once; another identity's
+answer cannot reserve the wallet's entry. Apps query by request hash and
+validate each candidate's ciphertext and granted keys against its `$ownerId`.
+
+On re-login the wallet deletes its old response **by values** and creates the
+new response. It retains the previous request hash, wallet key and ciphertext
+for deletion; retaining only a document ID is insufficient for an index-only
+type. See [the protocol guide](../../docs/protocol/app-connect.md) for details.
+
+## Install
+
+```sh
+npm install @dashevo/app-connect-contract
+```
+
+## License
+
+[MIT](LICENSE) © Dash Core Group, Inc.

package/eslint.config.mjs

@@ -0,0 +1,10 @@
+import baseConfig from '../../eslint/base.mjs';
+import mochaTestConfig from '../../eslint/mocha-tests.mjs';
+
+export default [
+  ...baseConfig,
+  mochaTestConfig,
+  {
+    ignores: ['dist/**', 'node_modules/**'],
+  },
+];

package/lib/systemIds.js

@@ -0,0 +1,4 @@
+module.exports = {
+  ownerId: '11111111111111111111111111111111',
+  contractId: 'H8F9mP1BM55TE1ShsxPZHzhyinaMdY9bMmP85mkDhcJJ',
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@dashevo/app-connect-contract",
+  "version": "4.2.0-beta.4",
+  "description": "A system contract for encrypted wallet-to-app login responses",
+  "scripts": {
+    "lint": "eslint .",
+    "test": "yarn run test:unit",
+    "test:unit": "mocha 'test/unit/**/*.spec.js'"
+  },
+  "contributors": [
+    {
+      "name": "Pasta",
+      "email": "pasta@dashboost.org",
+      "url": "https://github.com/PastaPastaPasta"
+    }
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@dashevo/wasm-dpp": "workspace:*",
+    "chai": "^4.3.10",
+    "dirty-chai": "^2.0.1",
+    "eslint": "^9.18.0",
+    "mocha": "^11.1.0",
+    "sinon": "^18.0.1",
+    "sinon-chai": "^3.7.0"
+  }
+}

package/schema/v1/app-connect-contract-documents.json

@@ -0,0 +1,55 @@
+{
+  "loginKeyResponse": {
+    "type": "object",
+    "documentsMutable": false,
+    "canBeDeleted": true,
+    "creationRestrictionMode": 0,
+    "indices": [
+      {
+        "name": "byRequest",
+        "terminal": [
+          "appEphemeralPubKeyHash",
+          "$ownerId"
+        ]
+      }
+    ],
+    "properties": {
+      "appEphemeralPubKeyHash": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 20,
+        "maxItems": 20,
+        "description": "hash160 of the ephemeral public key the app put in its connect request; identifies the request",
+        "position": 0
+      },
+      "walletEphemeralPubKey": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 33,
+        "maxItems": 33,
+        "description": "The wallet's compressed ephemeral public key; the app derives the shared secret from it and its own ephemeral private key",
+        "position": 1
+      },
+      "encryptedPayload": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 60,
+        "maxItems": 572,
+        "description": "The granted private keys encrypted to the app: a 28-byte envelope plus 32 bytes per key, one to seventeen keys (the session key plus up to eight bindings with both purposes)",
+        "position": 2
+      }
+    },
+    "required": [
+      "appEphemeralPubKeyHash",
+      "walletEphemeralPubKey",
+      "encryptedPayload"
+    ],
+    "description": "A wallet's response after approving a login request. The flat entry is keyed by the request hash and wallet identity, so other identities cannot block its write. On re-login the wallet deletes its previous response by values and creates a response for the new request.",
+    "additionalProperties": false,
+    "indexOnly": true,
+    "entryPayload": [
+      "walletEphemeralPubKey",
+      "encryptedPayload"
+    ]
+  }
+}

package/src/error.rs

@@ -0,0 +1,17 @@
+use platform_version::version::FeatureVersion;
+
+#[derive(thiserror::Error, Debug)]
+pub enum Error {
+    /// Platform expected some specific versions
+    #[error("platform unknown version on {method}, received: {received}")]
+    UnknownVersionMismatch {
+        /// method
+        method: String,
+        /// the allowed versions for this method
+        known_versions: Vec<FeatureVersion>,
+        /// requested core height
+        received: FeatureVersion,
+    },
+    #[error("schema deserialize error: {0}")]
+    InvalidSchemaJson(#[from] serde_json::Error),
+}

package/src/lib.rs

@@ -0,0 +1,66 @@
+mod error;
+pub mod v1;
+
+pub use crate::error::Error;
+use platform_value::{Identifier, IdentifierBytes32};
+use platform_version::version::PlatformVersion;
+use serde_json::Value;
+
+pub const ID_BYTES: [u8; 32] = [
+    239, 150, 14, 165, 105, 114, 235, 173, 190, 248, 162, 126, 247, 218, 92, 129, 255, 75, 179,
+    138, 2, 150, 151, 69, 126, 36, 218, 66, 183, 155, 84, 183,
+];
+
+pub const OWNER_ID_BYTES: [u8; 32] = [0; 32];
+
+pub const ID: Identifier = Identifier(IdentifierBytes32(ID_BYTES));
+pub const OWNER_ID: Identifier = Identifier(IdentifierBytes32(OWNER_ID_BYTES));
+/// The contract's definitions for `platform_version`. Version 0, the value the tables of
+/// protocol versions below 14 carry, names no schema generation and is refused like any
+/// unknown version: the contract does not exist before its activation.
+pub fn load_definitions(platform_version: &PlatformVersion) -> Result<Option<Value>, Error> {
+    match platform_version.system_data_contracts.app_connect {
+        1 => Ok(None),
+        version => Err(Error::UnknownVersionMismatch {
+            method: "app_connect_contract::load_definitions".to_string(),
+            known_versions: vec![1],
+            received: version,
+        }),
+    }
+}
+pub fn load_documents_schemas(platform_version: &PlatformVersion) -> Result<Value, Error> {
+    match platform_version.system_data_contracts.app_connect {
+        1 => v1::load_documents_schemas(),
+        version => Err(Error::UnknownVersionMismatch {
+            method: "app_connect_contract::load_documents_schemas".to_string(),
+            known_versions: vec![1],
+            received: version,
+        }),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use base58::FromBase58;
+
+    use super::*;
+
+    #[test]
+    /// Ensure that the ID constant matches the expected value
+    /// and that it can be encoded to base58 correctly.
+    fn should_match_the_published_system_contract_id() {
+        assert_eq!(
+            ID,
+            Identifier(IdentifierBytes32(ID_BYTES)),
+            "ID should match the expected value"
+        );
+
+        let base58_decoded = "H8F9mP1BM55TE1ShsxPZHzhyinaMdY9bMmP85mkDhcJJ"
+            .from_base58()
+            .unwrap();
+        assert_eq!(
+            base58_decoded, ID_BYTES,
+            "ID should match the base58 decoded value"
+        );
+    }
+}

package/src/v1/mod.rs

@@ -0,0 +1,25 @@
+use crate::Error;
+use serde_json::Value;
+
+pub mod document_types {
+    pub mod login_key_response {
+        pub const NAME: &str = "loginKeyResponse";
+
+        pub mod properties {
+            pub const APP_EPHEMERAL_PUB_KEY_HASH: &str = "appEphemeralPubKeyHash";
+            pub const WALLET_EPHEMERAL_PUB_KEY: &str = "walletEphemeralPubKey";
+            pub const ENCRYPTED_PAYLOAD: &str = "encryptedPayload";
+        }
+
+        pub mod indexes {
+            pub const BY_REQUEST: &str = "byRequest";
+        }
+    }
+}
+
+pub fn load_documents_schemas() -> Result<Value, Error> {
+    serde_json::from_str(include_str!(
+        "../../schema/v1/app-connect-contract-documents.json"
+    ))
+    .map_err(Error::InvalidSchemaJson)
+}

package/test/bootstrap.js

@@ -0,0 +1,30 @@
+const sinon = require('sinon');
+const sinonChai = require('sinon-chai');
+
+const { expect, use } = require('chai');
+const dirtyChai = require('dirty-chai');
+
+const {
+  default: loadWasmDpp,
+} = require('@dashevo/wasm-dpp');
+
+use(dirtyChai);
+use(sinonChai);
+
+exports.mochaHooks = {
+  beforeAll: loadWasmDpp,
+
+  beforeEach() {
+    if (!this.sinon) {
+      this.sinon = sinon.createSandbox();
+    } else {
+      this.sinon.restore();
+    }
+  },
+
+  afterEach() {
+    this.sinon.restore();
+  },
+};
+
+global.expect = expect;

package/test/unit/appConnectContract.spec.js

@@ -0,0 +1,199 @@
+const crypto = require('crypto');
+
+const {
+  DashPlatformProtocol,
+  JsonSchemaError,
+} = require('@dashevo/wasm-dpp');
+const generateRandomIdentifier = require('@dashevo/wasm-dpp/lib/test/utils/generateRandomIdentifierAsync');
+
+const { expect } = require('chai');
+const appConnectContractDocumentsSchema = require('../../schema/v1/app-connect-contract-documents.json');
+
+const expectJsonSchemaError = (validationResult, errorCount = 1) => {
+  const errors = validationResult.getErrors();
+  expect(errors)
+    .to
+    .have
+    .length(errorCount);
+
+  const error = validationResult.getErrors()[0];
+  expect(error)
+    .to
+    .be
+    .instanceof(JsonSchemaError);
+
+  return error;
+};
+
+describe('App Connect Contract', () => {
+  let dpp;
+  let dataContract;
+  let identityId;
+
+  beforeEach(async () => {
+    dpp = new DashPlatformProtocol(
+      { generate: () => crypto.randomBytes(32) },
+    );
+
+    identityId = await generateRandomIdentifier();
+
+    dataContract = dpp.dataContract.create(
+      identityId,
+      BigInt(1),
+      appConnectContractDocumentsSchema,
+    );
+  });
+
+  it('should have a valid contract definition', async () => {
+    expect(() => dpp.dataContract.create(
+      identityId,
+      BigInt(1),
+      appConnectContractDocumentsSchema,
+    ))
+      .to
+      .not
+      .throw();
+  });
+
+  describe('documents', () => {
+    describe('loginKeyResponse', () => {
+      let rawLoginKeyResponseDocument;
+
+      beforeEach(() => {
+        rawLoginKeyResponseDocument = {
+          appEphemeralPubKeyHash: crypto.randomBytes(20),
+          walletEphemeralPubKey: crypto.randomBytes(33),
+          encryptedPayload: crypto.randomBytes(60),
+        };
+      });
+
+      describe('appEphemeralPubKeyHash', () => {
+        it('should be defined', async () => {
+          delete rawLoginKeyResponseDocument.appEphemeralPubKeyHash;
+
+          const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+          const error = expectJsonSchemaError(validationResult);
+
+          expect(error.keyword).to.equal('required');
+          expect(error.params.missingProperty).to.equal('appEphemeralPubKeyHash');
+        });
+
+        it('should be not shorter than 20 bytes', async () => {
+          rawLoginKeyResponseDocument.appEphemeralPubKeyHash = crypto.randomBytes(19);
+
+          const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+          const error = expectJsonSchemaError(validationResult);
+
+          expect(error.keyword).to.equal('minItems');
+        });
+
+        it('should be not longer than 20 bytes', async () => {
+          rawLoginKeyResponseDocument.appEphemeralPubKeyHash = crypto.randomBytes(21);
+
+          const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+          const error = expectJsonSchemaError(validationResult);
+
+          expect(error.keyword).to.equal('maxItems');
+        });
+      });
+
+      describe('walletEphemeralPubKey', () => {
+        it('should be defined', async () => {
+          delete rawLoginKeyResponseDocument.walletEphemeralPubKey;
+
+          const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+          const error = expectJsonSchemaError(validationResult);
+
+          expect(error.keyword).to.equal('required');
+          expect(error.params.missingProperty).to.equal('walletEphemeralPubKey');
+        });
+
+        it('should be not shorter than 33 bytes', async () => {
+          rawLoginKeyResponseDocument.walletEphemeralPubKey = crypto.randomBytes(32);
+
+          const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+          const error = expectJsonSchemaError(validationResult);
+
+          expect(error.keyword).to.equal('minItems');
+        });
+
+        it('should be not longer than 33 bytes', async () => {
+          rawLoginKeyResponseDocument.walletEphemeralPubKey = crypto.randomBytes(34);
+
+          const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+          const error = expectJsonSchemaError(validationResult);
+
+          expect(error.keyword).to.equal('maxItems');
+        });
+      });
+
+      describe('encryptedPayload', () => {
+        it('should be defined', async () => {
+          delete rawLoginKeyResponseDocument.encryptedPayload;
+
+          const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+          const error = expectJsonSchemaError(validationResult);
+
+          expect(error.keyword).to.equal('required');
+          expect(error.params.missingProperty).to.equal('encryptedPayload');
+        });
+
+        it('should be not shorter than 60 bytes', async () => {
+          rawLoginKeyResponseDocument.encryptedPayload = crypto.randomBytes(59);
+
+          const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+          const error = expectJsonSchemaError(validationResult);
+
+          expect(error.keyword).to.equal('minItems');
+        });
+
+        it('should be not longer than 572 bytes', async () => {
+          rawLoginKeyResponseDocument.encryptedPayload = crypto.randomBytes(573);
+
+          const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+          const error = expectJsonSchemaError(validationResult);
+
+          expect(error.keyword).to.equal('maxItems');
+        });
+
+        it('should accept the maximum grant of seventeen keys', async () => {
+          // Session key plus eight bindings asking for both
+          // purposes: 28-byte envelope + 17 * 32 = 572 bytes.
+          rawLoginKeyResponseDocument.encryptedPayload = crypto.randomBytes(28 + (17 * 32));
+
+          const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+
+          expect(validationResult.isValid()).to.be.true();
+        });
+      });
+
+      it('should not have additional properties', async () => {
+        rawLoginKeyResponseDocument.someOtherProperty = 42;
+
+        const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+        const validationResult = document.validate(dpp.protocolVersion);
+        const error = expectJsonSchemaError(validationResult);
+
+        expect(error.keyword).to.equal('additionalProperties');
+        expect(error.params.additionalProperties).to.deep.equal(['someOtherProperty']);
+      });
+
+      it('should be valid', async () => {
+        const document = dpp.document.create(dataContract, identityId, 'loginKeyResponse', rawLoginKeyResponseDocument);
+        const validationResult = document.validate(dpp.protocolVersion);
+
+        expect(validationResult.isValid()).to.be.true();
+      });
+    });
+  });
+});