feat(platform)!: add contract-scoped authentication keys

docs/protocol/contract-scoped-authentication.md

@@ -0,0 +1,106 @@
+# Contract-scoped authentication keys
+
+Protocol version 14 adds application authentication scopes. A wallet can register
+a separate key for an application while retaining the identity's master key.
+Validators enforce the registered scope on every batch member. Existing identity
+ownership, key purpose, security level and document rules still apply.
+
+## Registering an application key
+
+The key must have AUTHENTICATION purpose and a non-MASTER security level. A HIGH
+key is suitable for normal document operations. Its `contractBounds` is a new
+`scoped` variant containing a versioned authentication scope:
+
+- `contracts`: explicit contract IDs with optional document-type restrictions.
+- `permissions`: an action bitmask shared by every listed contract.
+- `expiresAt`: an optional expiry in milliseconds, checked against block time.
+
+A missing/null document-type restriction authorizes all types in that contract,
+including types added by later contract updates. An empty array is invalid.
+Contract IDs and document-type names must be sorted and unique on the wire. There
+are at most 16 contracts and 16 types per contract, and the encoded scope must not
+exceed 2048 bytes. The WASM constructor sorts entries and rejects duplicates.
+
+For an application that creates, updates and deletes documents and pays their
+configured token fees, construct the bounds with the WASM SDK:
+
+```javascript
+const P = wasm.AuthenticationPermission;
+const bounds = wasm.ContractBounds.Scoped(
+  [
+    { id: socialContractId, documentTypes: ['like', 'post'] },
+    { id: profileContractId, documentTypes: ['profile'] },
+  ],
+  P.DocumentCreate | P.DocumentReplace | P.DocumentDelete | P.DocumentTokenPayment,
+  BigInt(Date.now() + 24 * 60 * 60 * 1000),
+);
+
+const keyToAdd = new wasm.IdentityPublicKeyInCreation({
+  keyId: nextKeyId,
+  purpose: 'authentication',
+  securityLevel: 'high',
+  keyType: 'ecdsa_hash160',
+  isReadOnly: false,
+  data: applicationPublicKeyHash160,
+  signature: new Uint8Array(),
+  contractBounds: bounds,
+});
+```
+
+Use the normal wallet-authorized identity-update procedure to register the key.
+The registration signature binds the scope as well as the public-key material.
+The browser only needs the application key's private material. Registering a
+scope requires its referenced contracts/types to exist and its expiry, if any,
+to be in the future. No contract encryption-key opt-in or unique-key setting is
+required for scoped authentication.
+
+## Permissions and token fees
+
+Document create, replace, delete, ownership transfer, price updates and purchases
+have separate bits. Index-only deletion uses the delete bit. Standalone token
+transition kinds also have separate bits. New/unknown bits are rejected.
+
+`DocumentTokenPayment` permits the actual contract-defined token cost of an
+otherwise-authorized document action. It also covers fees using a token issued
+by another contract. That does not authorize document writes or standalone token
+operations on the issuing contract. Without the bit, a document action with a
+positive token cost is rejected, even if its create/replace/delete bit is set.
+
+A document-token payment permission does not implicitly authorize token transfer,
+burn, mint, purchase or administration transitions. Explicitly granting one of
+those bits still cannot override its normal purpose/security/ownership rules.
+Contract updates can change document token fees; v0 scopes do not pin the fee
+amount or currency.
+
+## Expiry, revocation and failures
+
+A key is expired when executing block time is greater than or equal to its expiry.
+Mempool checks use the last committed block information; a transaction may expire
+between admission and execution. Disable the key through the normal identity
+update to revoke it. Extending expiry or expanding permissions requires a
+wallet-authorized replacement. Expired keys are not automatically deleted.
+
+Scoped keys cannot execute non-batch transitions, including identity-key updates,
+contract creation/updates, credit transfers/withdrawals or masternode votes.
+Expired keys and non-batch use fail in identity-signature authorization.
+
+Batch scope violations follow normal paid validation-failure handling. Requested
+document/token operations do not execute, but Platform credit validation fees
+can be charged and the first batch member's identity-contract nonce can advance,
+even if that member is outside the scope. Replays follow the usual nonce rules.
+
+There are no per-key budgets in scope version 0. A stolen key can exhaust credit
+balances through fees and permitted token balances through allowed operations.
+Expiry limits the time window, not total financial loss.
+
+## Compatibility
+
+The scoped variant is appended to the existing bounds enum; old key encodings
+remain unchanged. Older protocols reject scoped registration, and older clients
+cannot be assumed to decode scoped keys. SDK signing performs local structural
+checks, but validator checks against current state remain authoritative.
+
+The native key ABI carries an encoded scope pointer/length. Native libraries,
+generated headers and Swift/Kotlin consumers must be updated together. Key query,
+persistence, restore and refresh paths must preserve scope metadata. It must
+never be dropped or reconstructed as an unrestricted key.

packages/rs-dpp/src/errors/consensus/basic/basic_error.rs

@@ -1,3 +1,4 @@
+use crate::consensus::basic::identity::InvalidAuthenticationScopeError;
 use crate::errors::ProtocolError;
 use bincode::{Decode, Encode};
 use platform_serialization_derive::{PlatformDeserialize, PlatformSerialize};
@@ -699,6 +700,8 @@ pub enum BasicError {
 
     #[error(transparent)]
     DataContractInvalidRequiredFieldsUpdateError(DataContractInvalidRequiredFieldsUpdateError),
+    #[error(transparent)]
+    InvalidAuthenticationScopeError(InvalidAuthenticationScopeError),
 }
 
 impl From<BasicError> for ConsensusError {

packages/rs-dpp/src/errors/consensus/basic/identity/invalid_authentication_scope_error.rs

@@ -0,0 +1,28 @@
+use crate::consensus::basic::BasicError;
+use crate::consensus::ConsensusError;
+use crate::ProtocolError;
+use bincode::{Decode, Encode};
+use platform_serialization_derive::{PlatformDeserialize, PlatformSerialize};
+use thiserror::Error;
+
+#[derive(
+    Error, Debug, Clone, PartialEq, Eq, Encode, Decode, PlatformSerialize, PlatformDeserialize,
+)]
+#[error("Invalid authentication scope: {reason}")]
+#[platform_serialize(unversioned)]
+pub struct InvalidAuthenticationScopeError {
+    reason: String,
+}
+impl InvalidAuthenticationScopeError {
+    pub fn new(reason: String) -> Self {
+        Self { reason }
+    }
+    pub fn reason(&self) -> &String {
+        &self.reason
+    }
+}
+impl From<InvalidAuthenticationScopeError> for ConsensusError {
+    fn from(error: InvalidAuthenticationScopeError) -> Self {
+        Self::BasicError(BasicError::InvalidAuthenticationScopeError(error))
+    }
+}

packages/rs-dpp/src/errors/consensus/basic/identity/mod.rs

@@ -68,3 +68,6 @@ mod missing_master_public_key_error;
 mod not_implemented_credit_withdrawal_transition_pooling_error;
 mod too_many_master_public_key_error;
 mod withdrawal_output_script_not_allowed_when_signing_with_owner_key;
+
+mod invalid_authentication_scope_error;
+pub use invalid_authentication_scope_error::InvalidAuthenticationScopeError;

packages/rs-dpp/src/errors/consensus/codes.rs

@@ -205,6 +205,7 @@ impl ErrorWithCode for BasicError {
             Self::WithdrawalOutputScriptNotAllowedWhenSigningWithOwnerKeyError(_) => 10532,
             Self::InvalidKeyPurposeForContractBoundsError(_) => 10533,
             Self::IdentityAssetLockTransactionTooManyInputsError(_) => 10534,
+            Self::InvalidAuthenticationScopeError(_) => 10535,
 
             // State Transition Errors: 10600-10699
             Self::InvalidStateTransitionTypeError { .. } => 10600,
@@ -264,6 +265,9 @@ impl ErrorWithCode for SignatureError {
             Self::BasicBLSError(_) => 20010,
             Self::InvalidSignaturePublicKeyPurposeError(_) => 20011,
             Self::UncompressedPublicKeyNotAllowedError(_) => 20012,
+            Self::ScopedKeyOutOfScopeError(_) => 20015,
+            Self::ScopedKeyExpiredError(_) => 20014,
+            Self::ScopedKeyNonBatchError(_) => 20013,
         }
     }
 }

packages/rs-dpp/src/errors/consensus/signature/mod.rs

@@ -27,3 +27,12 @@ pub use crate::consensus::signature::signature_error::SignatureError;
 pub use crate::consensus::signature::signature_should_not_be_present_error::SignatureShouldNotBePresentError;
 pub use crate::consensus::signature::uncompressed_public_key_not_allowed_error::UncompressedPublicKeyNotAllowedError;
 pub use crate::consensus::signature::wrong_public_key_purpose_error::WrongPublicKeyPurposeError;
+
+mod scoped_key_non_batch_error;
+pub use scoped_key_non_batch_error::ScopedKeyNonBatchError;
+
+mod scoped_key_expired_error;
+pub use scoped_key_expired_error::ScopedKeyExpiredError;
+
+mod scoped_key_out_of_scope_error;
+pub use scoped_key_out_of_scope_error::ScopedKeyOutOfScopeError;

packages/rs-dpp/src/errors/consensus/signature/scoped_key_expired_error.rs

@@ -0,0 +1,28 @@
+use crate::consensus::signature::SignatureError;
+use crate::consensus::ConsensusError;
+use crate::ProtocolError;
+use bincode::{Decode, Encode};
+use platform_serialization_derive::{PlatformDeserialize, PlatformSerialize};
+use thiserror::Error;
+
+#[derive(
+    Error, Debug, Clone, PartialEq, Eq, Encode, Decode, PlatformSerialize, PlatformDeserialize,
+)]
+#[error("Scoped key {public_key_id} has expired")]
+#[platform_serialize(unversioned)]
+pub struct ScopedKeyExpiredError {
+    public_key_id: u32,
+}
+impl ScopedKeyExpiredError {
+    pub fn new(public_key_id: u32) -> Self {
+        Self { public_key_id }
+    }
+    pub fn public_key_id(&self) -> &u32 {
+        &self.public_key_id
+    }
+}
+impl From<ScopedKeyExpiredError> for ConsensusError {
+    fn from(error: ScopedKeyExpiredError) -> Self {
+        Self::SignatureError(SignatureError::ScopedKeyExpiredError(error))
+    }
+}

packages/rs-dpp/src/errors/consensus/signature/scoped_key_non_batch_error.rs

@@ -0,0 +1,28 @@
+use crate::consensus::signature::SignatureError;
+use crate::consensus::ConsensusError;
+use crate::ProtocolError;
+use bincode::{Decode, Encode};
+use platform_serialization_derive::{PlatformDeserialize, PlatformSerialize};
+use thiserror::Error;
+
+#[derive(
+    Error, Debug, Clone, PartialEq, Eq, Encode, Decode, PlatformSerialize, PlatformDeserialize,
+)]
+#[error("Scoped key {public_key_id} cannot sign a non-batch transition")]
+#[platform_serialize(unversioned)]
+pub struct ScopedKeyNonBatchError {
+    public_key_id: u32,
+}
+impl ScopedKeyNonBatchError {
+    pub fn new(public_key_id: u32) -> Self {
+        Self { public_key_id }
+    }
+    pub fn public_key_id(&self) -> &u32 {
+        &self.public_key_id
+    }
+}
+impl From<ScopedKeyNonBatchError> for ConsensusError {
+    fn from(error: ScopedKeyNonBatchError) -> Self {
+        Self::SignatureError(SignatureError::ScopedKeyNonBatchError(error))
+    }
+}

packages/rs-dpp/src/errors/consensus/signature/scoped_key_out_of_scope_error.rs

@@ -0,0 +1,28 @@
+use crate::consensus::signature::SignatureError;
+use crate::consensus::ConsensusError;
+use crate::ProtocolError;
+use bincode::{Decode, Encode};
+use platform_serialization_derive::{PlatformDeserialize, PlatformSerialize};
+use thiserror::Error;
+
+#[derive(
+    Error, Debug, Clone, PartialEq, Eq, Encode, Decode, PlatformSerialize, PlatformDeserialize,
+)]
+#[error("Batch member is outside key {public_key_id} scope")]
+#[platform_serialize(unversioned)]
+pub struct ScopedKeyOutOfScopeError {
+    public_key_id: u32,
+}
+impl ScopedKeyOutOfScopeError {
+    pub fn new(public_key_id: u32) -> Self {
+        Self { public_key_id }
+    }
+    pub fn public_key_id(&self) -> &u32 {
+        &self.public_key_id
+    }
+}
+impl From<ScopedKeyOutOfScopeError> for ConsensusError {
+    fn from(error: ScopedKeyOutOfScopeError) -> Self {
+        Self::SignatureError(SignatureError::ScopedKeyOutOfScopeError(error))
+    }
+}

packages/rs-dpp/src/errors/consensus/signature/signature_error.rs

@@ -1,3 +1,6 @@
+use crate::consensus::signature::ScopedKeyExpiredError;
+use crate::consensus::signature::ScopedKeyNonBatchError;
+use crate::consensus::signature::ScopedKeyOutOfScopeError;
 use crate::consensus::signature::{
     BasicBLSError, BasicECDSAError, IdentityNotFoundError, InvalidIdentityPublicKeyTypeError,
     InvalidSignaturePublicKeySecurityLevelError, InvalidStateTransitionSignatureError,
@@ -60,6 +63,14 @@ pub enum SignatureError {
 
     #[error(transparent)]
     UncompressedPublicKeyNotAllowedError(UncompressedPublicKeyNotAllowedError),
+    #[error(transparent)]
+    ScopedKeyNonBatchError(ScopedKeyNonBatchError),
+
+    #[error(transparent)]
+    ScopedKeyExpiredError(ScopedKeyExpiredError),
+
+    #[error(transparent)]
+    ScopedKeyOutOfScopeError(ScopedKeyOutOfScopeError),
 }
 
 impl From<SignatureError> for ConsensusError {

packages/rs-dpp/src/identity/identity.rs

@@ -29,6 +29,11 @@ use std::collections::{BTreeMap, BTreeSet};
 /// The identity is not stored inside of drive, because of this, the serialization is mainly for
 /// transport, the serialization of the identity will include the version, so no passthrough or
 /// untagged is needed here
+///
+/// The 256 MiB decoding budget accommodates `IDENTITY_MAX_KEYS` (15,000) at
+/// 16 KiB per scoped key, plus the key map and identity fields. Bincode counts
+/// container allocations as well as wire bytes. Individual authentication scopes
+/// still have a separate 2 KiB wire limit enforced by scope validation.
 #[derive(Debug, Clone, PartialEq, From)]
 #[cfg_attr(
    feature = "serde-conversion",
@@ -39,7 +44,7 @@ use std::collections::{BTreeMap, BTreeSet};
 #[cfg_attr(
     feature = "identity-serialization",
     derive(Encode, Decode, PlatformDeserialize, PlatformSerialize),
-    platform_serialize(limit = 15000, unversioned)
+    platform_serialize(limit = 268435456, unversioned)
 )]
 #[cfg_attr(feature = "value-conversion", derive(ValueConvertible))]
 pub enum Identity {
@@ -335,6 +340,81 @@ mod tests {
         })
     }
 
+    #[cfg(feature = "identity-serialization")]
+    #[test]
+    fn should_decode_full_identities_with_large_scoped_key_sets() {
+        use crate::identity::contract_bounds::{
+            authentication_scope::permissions, AuthenticationScope, AuthenticationScopeV0,
+            ContractBounds, ContractScope,
+        };
+        use crate::identity::fields::IDENTITY_MAX_KEYS;
+        use crate::serialization::{PlatformDeserializable, PlatformSerializable};
+
+        let scope = AuthenticationScope::V0(AuthenticationScopeV0 {
+            contracts: (1..=16)
+                .map(|id| ContractScope {
+                    id: Identifier::from([id; 32]),
+                    document_types: Some((0..16).map(|n| format!("t{n:03}")).collect()),
+                })
+                .collect(),
+            permissions: permissions::ALL,
+            expires_at: Some(u64::MAX),
+        });
+        scope.validate().unwrap();
+
+        for count in [8, u32::from(IDENTITY_MAX_KEYS)] {
+            let mut public_keys = BTreeMap::from([(0, sample_key(0))]);
+            for id in 1..count {
+                let mut key = IdentityPublicKeyV0 {
+                    id,
+                    key_type: KeyType::BLS12_381,
+                    purpose: Purpose::AUTHENTICATION,
+                    security_level: SecurityLevel::HIGH,
+                    contract_bounds: Some(ContractBounds::Scoped(scope.clone())),
+                    data: vec![0x42; 48].into(),
+                    read_only: false,
+                    disabled_at: None,
+                };
+                // Full identities retain disabled keys too.
+                if id % 2 == 0 {
+                    key.disabled_at = Some(u64::MAX);
+                }
+                public_keys.insert(id, key.into());
+            }
+            let identity: Identity = IdentityV0 {
+                id: Identifier::from([0x42; 32]),
+                public_keys,
+                balance: u64::MAX,
+                revision: u64::MAX,
+            }
+            .into();
+            let bytes = identity.serialize_to_bytes().unwrap();
+            assert_eq!(
+                Identity::deserialize_from_bytes(&bytes).unwrap(),
+                identity,
+                "full identity with {count} keys must round-trip"
+            );
+        }
+    }
+
+    #[cfg(feature = "identity-serialization")]
+    #[test]
+    fn should_reject_full_identity_with_excessive_declared_key_allocation() {
+        use crate::serialization::PlatformDeserializable;
+
+        // Valid V0 tag and identity ID, followed by a forged public-key map length.
+        // The decoder must enforce its allocation budget before reading any keys.
+        let bytes = bincode::encode_to_vec(
+            (0_u8, Identifier::from([0x42; 32]), u64::MAX),
+            bincode::config::standard().with_big_endian(),
+        )
+        .unwrap();
+        assert!(matches!(
+            Identity::deserialize_from_bytes(&bytes),
+            Err(ProtocolError::MaxEncodedBytesReachedError { .. })
+        ));
+    }
+
     #[test]
     fn default_versioned_returns_default_v0() {
         let identity =