feat(platform)!: encryptedFor envelope declaration on byte properties (PV14)

book/src/data-model/documents.md

@@ -364,6 +364,45 @@ A transfer or purchase changes `$ownerId` without touching the data, so the tran
 
 In Rust the declaration is `DocumentProperty::distinct_from` (`Option<DistinctFrom>`, absent on every property parsed before protocol version 14), the document check is `DocumentTypeV0Methods::validate_distinct_from_properties`, and `DistinctFrom::violation` judges one value on its own, which is how the elements of a typed array are judged one by one.
 
+## Encrypted Properties (`encryptedFor`)
+
+A byte array property may hold ciphertext that only one identity can read. Before protocol version 14 the contract said nothing about it, so every wallet had to learn the recipe (whose keys, which scheme, where the IV sits) from documentation or a side channel. From protocol version 14 the property declares it with the `encryptedFor` keyword, and wallets and SDKs read the recipe from the contract.
+
+```json
+"encryptedMessage": {
+  "type": "array", "byteArray": true, "minItems": 32, "maxItems": 1040,
+  "encryptedFor": {
+    "recipient": "recipientId",
+    "recipientKey": "recipientKeyId",
+    "senderKey": "senderKeyId",
+    "scheme": "ecdh-secp256k1-aes256-cbc"
+  },
+  "position": 4
+}
+```
+
+All four keys are required. `recipient` is the dotted path of an identifier property of the same document type whose value is the recipient identity's id, or `$ownerId` for a message the writer encrypts to themself. `recipientKey` and `senderKey` are dotted paths of integer properties of the same document type carrying the recipient's and the sender's identity key ids; each must declare `minimum` at least 0 and `maximum` at most 4294967295, read from the schema itself, so the rule holds whatever `sizedIntegerTypes` the contract sets. `scheme` is a closed set with one member today.
+
+The parser (generation 3, meta-schema v3) admits the keyword on byte array properties only, never on an identifier (`contentMediaType` set) or any other type, and checks at contract registration that the three named properties exist with those types, that none of them is `transient` (a transient property is stripped before storage, which would leave the stored ciphertext without its recipe), and that the byte array's own `maxItems` can hold the scheme's shortest ciphertext. A contract update that adds, removes or changes an `encryptedFor` declaration is an incompatible schema change (`IncompatibleDocumentTypeSchemaError`, 10246): documents already written under the old recipe could not be read under the new one. Contracts parsed before protocol version 14 ignore the keyword entirely.
+
+### The `ecdh-secp256k1-aes256-cbc` layout
+
+This is the scheme the dashpay contact request already uses for `encryptedPublicKey` and `encryptedAccountLabel` (DIP-15), implemented in `packages/rs-platform-encryption`:
+
+1. The shared key is the libsecp256k1 ECDH of the sender's private key and the recipient's public key: `SHA256(parity || x)` of the product point, where `parity` is `0x02` for an even `y` and `0x03` for an odd one. The sender's key is the identity key with the id the `senderKey` property carries, on the document's `$ownerId` identity; the recipient's key is the one with the id the `recipientKey` property carries, on the identity the `recipient` property names (the owner itself for `$ownerId`). Either side derives the same 32 bytes from its own private key and the other's public key.
+2. The writer draws a random 16-byte IV.
+3. The value is the IV followed by the plaintext encrypted with AES-256-CBC under the shared key and that IV, with PKCS7 padding.
+
+So a ciphertext is `16 + 16 * ceil((len(plaintext) + 1) / 16)` bytes: at least 32, always a multiple of 16. The reader splits the first 16 bytes off as the IV, derives the shared key from its own private key and the sender's public key, and decrypts the rest.
+
+### What consensus checks, and what it cannot
+
+Consensus sees bytes, not keys. On every document create and replace, after the JSON schema validation of the document's properties, the structure validation (create structure generation 1, introduced at protocol version 14, and replace structure generation 0, extended in place: the call is inert before 14, where no property can carry the keyword) walks the document type's declared properties and, for each one the transition supplies, checks that its length is at least the scheme's IV plus one block and a multiple of the block length. A value that is not refuses the transition with `InvalidEncryptedPropertyShapeError` (basic code 10420), which names the property path, the scheme and the lengths involved. No state is read; the check runs in the mempool as well as in the block. The JSON schema's own `minItems` and `maxItems` are checked first, so a value outside them (a lone 16-byte IV against `minItems: 32`, say) is refused with the schema's error rather than 10420; the shape check only sees values the bounds already admit.
+
+Nothing else is verifiable on chain: not that the bytes decrypt, not that they decrypt under the keys the document names, not that the named key ids exist on the identities or have an encryption purpose, and not that the plaintext is what the document type means it to be. A writer can store any 32 bytes. Whether the keys exist and are of the right kind is what the reference keywords are for: a `refersTo` of type `identityPublicKey` with `keyIdProperty` on the recipient property makes consensus check that the recipient's key exists, and `encryptedFor` neither duplicates nor requires it. Readers must treat a value that fails to decrypt as a bad message, not as a protocol violation.
+
+In Rust the declaration is `DocumentProperty::encrypted_for` (`Option<EncryptedFor>`), listed per document type by `DocumentTypeV0Getters::encrypted_properties()`, and the shape check is `DocumentTypeBasicMethods::validate_encrypted_property_shapes()`, versioned on the `validate_encrypted_property_shapes` method slot (`None` before protocol version 14, which is what keeps the in-place replace call inert). In JavaScript, `contract.documentTypeEncryptedProperties(name)` and `contract.documentEncryptedProperties` expose the same declarations, and the shape error reaches an app as `DocumentEncryptionErrorCode.InvalidEncryptedPropertyShape`.
+
 ## Rules and Guidelines
 
 **Do:**

book/src/error-handling/error-codes.md

@@ -53,7 +53,7 @@ Error codes are organized into ranges that correspond to error categories and su
 | 10200-10277 | Data Contract | `DataContractMaxDepthExceedError` (10200), `DuplicateIndexError` (10201), `InvalidDataContractIdError` (10204), `DataContractInvalidRequiredFieldsUpdateError` (10276), `PreProgrammedDistributionAmountOverLimitError` (10277) |
 | 10350-10359 | Groups | `GroupPositionDoesNotExistError` (10350), `GroupExceedsMaxMembersError` (10354) |
 | 10360-10367 | Contract Groups | `ContractGroupMembershipsOverLimitError` (10360), `InvalidContractGroupAdminsError` (10364), `InvalidContractGroupDescriptionLengthError` (10367); 10365 unassigned |
-| 10400-10419 | Documents | `DataContractNotPresentError` (10400), `DuplicateDocumentTransitionsWithIdsError` (10401), `DocumentPropertyNotDistinctError` (10419) |
+| 10400-10420 | Documents | `DataContractNotPresentError` (10400), `DuplicateDocumentTransitionsWithIdsError` (10401), `DocumentPropertyNotDistinctError` (10419), `InvalidEncryptedPropertyShapeError` (10420) |
 | 10450-10460 | Tokens | `InvalidTokenIdError` (10450), `TokenTransferToOurselfError` (10456) |
 | 10500-10535 | Identity | `DuplicatedIdentityPublicKeyBasicError` (10500), `InvalidIdentityPublicKeyDataError` (10511) |
 | 10600-10603 | State Transition | `InvalidStateTransitionTypeError` (10600), `StateTransitionMaxSizeExceededError` (10602) |

packages/js-evo-sdk/README.md

@@ -241,6 +241,42 @@ const stateTransition = batch.toStateTransition();
 
 From protocol version 14 the id of a new document commits to the identity contract nonce of its create transition. `new DocumentCreateTransition(...)` derives that id from the document's entropy and `identityContractNonce`, puts it on the transition and writes it back onto `document`, so `document.id` is final once the transition exists and equals `transition.base.id`. Before that the `Document` carries a placeholder. To know the id earlier, `document.setIdForCreation(nonce)` or `Document.generateId(type, owner, contract, entropy, nonce)`, or pass `identityContractNonce` to the `Document` constructor. Pass `platformVersion` (defaults to latest) to any of them for a network on an earlier protocol version. No app needs to reimplement the hash.
 
+## Encrypted properties (`encryptedFor`)
+
+From protocol version 14 a byte array property can declare how its ciphertext was produced, so a wallet reads the recipe from the contract instead of a side channel: the recipient (an identifier property of the same document type, or `$ownerId` for a message the writer encrypts to themself), the integer properties carrying the recipient's and the sender's key ids, and the scheme. The one scheme today, `ecdh-secp256k1-aes256-cbc`, is the dashpay contact request's: a random 16-byte IV followed by AES-256-CBC with PKCS7 padding under the libsecp256k1 ECDH shared key of the two identities' keys. A fetched contract can be asked what it declares:
+
+```ts
+const contract = await sdk.contracts.fetch(contractId);
+
+contract.documentTypeEncryptedProperties('joinRequest');
+// [{
+//   path: 'encryptedMessage',
+//   recipient: 'recipientId',
+//   recipientKey: 'recipientKeyId',
+//   senderKey: 'senderKeyId',
+//   scheme: 'ecdh-secp256k1-aes256-cbc',
+// }]
+
+// Every document type that declares at least one encrypted property.
+contract.documentEncryptedProperties;
+```
+
+The keyword is only parsed from protocol version 14 onward; a contract deserialized against an earlier version reports none even when its raw schema carries it. Consensus checks only the shape of the bytes on every create and replace (at least 32 bytes and a multiple of 16 for AES-CBC) and nothing about who can decrypt them. A value of the wrong shape is rejected, and the code reaches JS as `error.code`:
+
+```ts
+import { DocumentEncryptionErrorCode } from '@dashevo/evo-sdk';
+
+try {
+  await sdk.documents.create({ document, identityKey, signer });
+} catch (e) {
+  if (e.code === DocumentEncryptionErrorCode.InvalidEncryptedPropertyShape) {
+    // the bytes are not a ciphertext of the declared scheme (code 10420)
+  }
+}
+```
+
+Encrypt and decrypt helpers keyed off the declaration are not part of the SDK yet; the Rust `platform-encryption` crate has the primitives.
+
 ## Immutable properties (`immutable`)
 
 From protocol version 14 a mutable document type can freeze some of its top-level properties at creation with the doctype-level `immutable` list, while the rest of the document stays replaceable. A second list, `immutableAllowSetting`, names the frozen properties a replace may still set while the stored document has no value for them; once present they are frozen too. Both are consensus-enforced on every replace, and a fetched contract can be asked what it declares:

packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json

@@ -95,6 +95,39 @@
           "description": "typed arrays only: the schema every element of the array has",
           "$ref": "#/$defs/documentArrayItem"
         },
+        "encryptedFor": {
+          "description": "byte array properties that are not identifiers only: how the property's ciphertext was produced, so wallets and SDKs read the recipe from the contract. recipient names an identifier property of the same document type whose value is the recipient identity's id, or is \"$ownerId\" for a message the writer encrypts to themself; recipientKey and senderKey name integer properties of the same document type (minimum at least 0, maximum at most 4294967295) carrying the recipient's and the sender's identity key ids; scheme names how the bytes were made. Under ecdh-secp256k1-aes256-cbc, the scheme of the dashpay contact request, the shared key is the libsecp256k1 ECDH of the sender's private key and the recipient's public key (SHA256 of the product point's parity byte and x coordinate) and the value is a random 16-byte IV followed by the plaintext under AES-256-CBC with PKCS7 padding and that IV, so at least 32 bytes and a multiple of 16. All four keys are required and the three named properties must exist with those types. Consensus checks only that shape on every create and replace (InvalidEncryptedPropertyShapeError, 10420): who can decrypt the bytes, and whether they decrypt at all, is not verifiable on chain",
+          "type": "object",
+          "properties": {
+            "recipient": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256
+            },
+            "recipientKey": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256
+            },
+            "senderKey": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256
+            },
+            "scheme": {
+              "enum": [
+                "ecdh-secp256k1-aes256-cbc"
+              ]
+            }
+          },
+          "required": [
+            "recipient",
+            "recipientKey",
+            "senderKey",
+            "scheme"
+          ],
+          "additionalProperties": false
+        },
         "refersTo": {
           "type": "object",
           "properties": {
@@ -445,6 +478,22 @@
             "maxItems"
           ]
         },
+        "encryptedFor": {
+          "description": "encryptedFor is only allowed on byte array properties that are not identifiers",
+          "properties": {
+            "type": {
+              "const": "array"
+            },
+            "byteArray": {
+              "const": true
+            },
+            "contentMediaType": false
+          },
+          "required": [
+            "type",
+            "byteArray"
+          ]
+        },
         "format": {
           "description": "prevent slow format validation of large strings",
           "properties": {

packages/rs-dpp/src/data_contract/document_type/accessors/v0/mod.rs

@@ -1,6 +1,6 @@
 use crate::data_contract::document_type::index::Index;
 use crate::data_contract::document_type::index_level::IndexLevel;
-use crate::data_contract::document_type::property::DocumentProperty;
+use crate::data_contract::document_type::property::{DocumentProperty, EncryptedFor};
 
 use platform_value::{Identifier, Value};
 
@@ -42,6 +42,23 @@ pub trait DocumentTypeV0Getters {
     /// Returns the properties of the document type.
     fn properties(&self) -> &IndexMap<String, DocumentProperty>;
 
+    /// The properties declared `encryptedFor`, each by its dotted path in
+    /// schema order, with the declaration that says for whom, under which
+    /// keys and under which scheme their bytes were encrypted. Empty on a
+    /// document type declaring none, and on every contract parsed before
+    /// protocol version 14, which ignores the keyword.
+    fn encrypted_properties(&self) -> Vec<(&String, &EncryptedFor)> {
+        self.flattened_properties()
+            .iter()
+            .filter_map(|(path, property)| {
+                property
+                    .encrypted_for
+                    .as_ref()
+                    .map(|encrypted_for| (path, encrypted_for))
+            })
+            .collect()
+    }
+
     /// Returns the identifier paths of the document type.
     fn identifier_paths(&self) -> &BTreeSet<String>;