@aptos-labs/ts-sdk 1.27.0 → 1.27.1-zeta.0

package/src/internal/move/jwks/build/jwk/sources/dependencies/AptosStdlib/capability.move

@@ -0,0 +1,193 @@
+/// A module which defines the basic concept of
+/// [*capabilities*](https://en.wikipedia.org/wiki/Capability-based_security) for managing access control.
+///
+/// EXPERIMENTAL
+///
+/// # Overview
+///
+/// A capability is a unforgeable token which testifies that a signer has authorized a certain operation.
+/// The token is valid during the transaction where it is obtained. Since the type `capability::Cap` has
+/// no ability to be stored in global memory, capabilities cannot leak out of a transaction. For every function
+/// called within a transaction which has a capability as a parameter, it is guaranteed that the capability
+/// has been obtained via a proper signer-based authorization step previously in the transaction's execution.
+///
+/// ## Usage
+///
+/// Initializing and acquiring capabilities is usually encapsulated in a module with a type
+/// tag which can only be constructed by this module.
+///
+/// ```
+/// module Pkg::Feature {
+///   use std::capability::Cap;
+///
+///   /// A type tag used in Cap<Feature>. Only this module can create an instance,
+///   /// and there is no public function other than Self::acquire which returns a value of this type.
+///   /// This way, this module has full control how Cap<Feature> is given out.
+///   struct Feature has drop {}
+///
+///   /// Initializes this module.
+///   public fun initialize(s: &signer) {
+///     // Create capability. This happens once at module initialization time.
+///     // One needs to provide a witness for being the owner of Feature
+///     // in the 2nd parameter.
+///     <<additional conditions allowing to initialize this capability>>
+///     capability::create<Feature>(s, &Feature{});
+///   }
+///
+///   /// Acquires the capability to work with this feature.
+///   public fun acquire(s: &signer): Cap<Feature> {
+///     <<additional conditions allowing to acquire this capability>>
+///     capability::acquire<Feature>(s, &Feature{});
+///   }
+///
+///   /// Does something related to the feature. The caller must pass a Cap<Feature>.
+///   public fun do_something(_cap: Cap<Feature>) { ... }
+/// }
+/// ```
+///
+/// ## Delegation
+///
+/// Capabilities come with the optional feature of *delegation*. Via `Self::delegate`, an owner of a capability
+/// can designate another signer to be also capable of acquiring the capability. Like the original creator,
+/// the delegate needs to present his signer to obtain the capability in his transactions. Delegation can
+/// be revoked via `Self::revoke`, removing this access right from the delegate.
+///
+/// While the basic authorization mechanism for delegates is the same as with core capabilities, the
+/// target of delegation might be subject of restrictions which need to be specified and verified. This can
+/// be done via global invariants in the specification language. For example, in order to prevent delegation
+/// all together for a capability, one can use the following invariant:
+///
+/// ```
+///   invariant forall a: address where capability::spec_has_cap<Feature>(a):
+///               len(capability::spec_delegates<Feature>(a)) == 0;
+/// ```
+///
+/// Similarly, the following invariant would enforce that delegates, if existent, must satisfy a certain
+/// predicate:
+///
+/// ```
+///   invariant forall a: address where capability::spec_has_cap<Feature>(a):
+///               forall d in capability::spec_delegates<Feature>(a):
+///                  is_valid_delegate_for_feature(d);
+/// ```
+///
+module aptos_std::capability {
+    use std::error;
+    use std::signer;
+    use std::vector;
+
+    /// Capability resource already exists on the specified account
+    const ECAPABILITY_ALREADY_EXISTS: u64 = 1;
+    /// Capability resource not found
+    const ECAPABILITY_NOT_FOUND: u64 = 2;
+    /// Account does not have delegated permissions
+    const EDELEGATE: u64 = 3;
+
+    /// The token representing an acquired capability. Cannot be stored in memory, but copied and dropped freely.
+    struct Cap<phantom Feature> has copy, drop {
+        root: address
+    }
+
+    /// A linear version of a capability token. This can be used if an acquired capability should be enforced
+    /// to be used only once for an authorization.
+    struct LinearCap<phantom Feature> has drop {
+        root: address
+    }
+
+    /// An internal data structure for representing a configured capability.
+    struct CapState<phantom Feature> has key {
+        delegates: vector<address>
+    }
+
+    /// An internal data structure for representing a configured delegated capability.
+    struct CapDelegateState<phantom Feature> has key {
+        root: address
+    }
+
+    /// Creates a new capability class, owned by the passed signer. A caller must pass a witness that
+    /// they own the `Feature` type parameter.
+    public fun create<Feature>(owner: &signer, _feature_witness: &Feature) {
+        let addr = signer::address_of(owner);
+        assert!(!exists<CapState<Feature>>(addr), error::already_exists(ECAPABILITY_ALREADY_EXISTS));
+        move_to<CapState<Feature>>(owner, CapState { delegates: vector::empty() });
+    }
+
+    /// Acquires a capability token. Only the owner of the capability class, or an authorized delegate,
+    /// can succeed with this operation. A caller must pass a witness that they own the `Feature` type
+    /// parameter.
+    public fun acquire<Feature>(requester: &signer, _feature_witness: &Feature): Cap<Feature>
+    acquires CapState, CapDelegateState {
+        Cap<Feature> { root: validate_acquire<Feature>(requester) }
+    }
+
+    /// Acquires a linear capability token. It is up to the module which owns `Feature` to decide
+    /// whether to expose a linear or non-linear capability.
+    public fun acquire_linear<Feature>(requester: &signer, _feature_witness: &Feature): LinearCap<Feature>
+    acquires CapState, CapDelegateState {
+        LinearCap<Feature> { root: validate_acquire<Feature>(requester) }
+    }
+
+    /// Helper to validate an acquire. Returns the root address of the capability.
+    fun validate_acquire<Feature>(requester: &signer): address
+    acquires CapState, CapDelegateState {
+        let addr = signer::address_of(requester);
+        if (exists<CapDelegateState<Feature>>(addr)) {
+            let root_addr = borrow_global<CapDelegateState<Feature>>(addr).root;
+            // double check that requester is actually registered as a delegate
+            assert!(exists<CapState<Feature>>(root_addr), error::invalid_state(EDELEGATE));
+            assert!(vector::contains(&borrow_global<CapState<Feature>>(root_addr).delegates, &addr),
+                error::invalid_state(EDELEGATE));
+            root_addr
+        } else {
+            assert!(exists<CapState<Feature>>(addr), error::not_found(ECAPABILITY_NOT_FOUND));
+            addr
+        }
+    }
+
+    /// Returns the root address associated with the given capability token. Only the owner
+    /// of the feature can do this.
+    public fun root_addr<Feature>(self: Cap<Feature>, _feature_witness: &Feature): address {
+        self.root
+    }
+
+    /// Returns the root address associated with the given linear capability token.
+    public fun linear_root_addr<Feature>(self: LinearCap<Feature>, _feature_witness: &Feature): address {
+        self.root
+    }
+
+    /// Registers a delegation relation. If the relation already exists, this function does
+    /// nothing.
+    // TODO: explore whether this should be idempotent like now or abort
+    public fun delegate<Feature>(self: Cap<Feature>, _feature_witness: &Feature, to: &signer)
+    acquires CapState {
+        let addr = signer::address_of(to);
+        if (exists<CapDelegateState<Feature>>(addr)) return;
+        move_to(to, CapDelegateState<Feature> { root: self.root });
+        add_element(&mut borrow_global_mut<CapState<Feature>>(self.root).delegates, addr);
+    }
+
+    /// Revokes a delegation relation. If no relation exists, this function does nothing.
+    // TODO: explore whether this should be idempotent like now or abort
+    public fun revoke<Feature>(self: Cap<Feature>, _feature_witness: &Feature, from: address)
+    acquires CapState, CapDelegateState
+    {
+        if (!exists<CapDelegateState<Feature>>(from)) return;
+        let CapDelegateState { root: _root } = move_from<CapDelegateState<Feature>>(from);
+        remove_element(&mut borrow_global_mut<CapState<Feature>>(self.root).delegates, &from);
+    }
+
+    /// Helper to remove an element from a vector.
+    fun remove_element<E: drop>(v: &mut vector<E>, x: &E) {
+        let (found, index) = vector::index_of(v, x);
+        if (found) {
+            vector::remove(v, index);
+        }
+    }
+
+    /// Helper to add an element to a vector.
+    fun add_element<E: drop>(v: &mut vector<E>, x: E) {
+        if (!vector::contains(v, &x)) {
+            vector::push_back(v, x)
+        }
+    }
+}

package/src/internal/move/jwks/build/jwk/sources/dependencies/AptosStdlib/comparator.move

@@ -0,0 +1,173 @@
+/// Provides a framework for comparing two elements
+module aptos_std::comparator {
+    use std::bcs;
+    use std::vector;
+
+    const EQUAL: u8 = 0;
+    const SMALLER: u8 = 1;
+    const GREATER: u8 = 2;
+
+    struct Result has drop {
+        inner: u8,
+    }
+
+    public fun is_equal(self: &Result): bool {
+        self.inner == EQUAL
+    }
+
+    public fun is_smaller_than(self: &Result): bool {
+        self.inner == SMALLER
+    }
+
+    public fun is_greater_than(self: &Result): bool {
+        self.inner == GREATER
+    }
+
+    // Performs a comparison of two types after BCS serialization.
+    // BCS uses little endian encoding for all integer types,
+    // so comparison between primitive integer types will not behave as expected.
+    // For example, 1(0x1) will be larger than 256(0x100) after BCS serialization.
+    public fun compare<T>(left: &T, right: &T): Result {
+        let left_bytes = bcs::to_bytes(left);
+        let right_bytes = bcs::to_bytes(right);
+
+        compare_u8_vector(left_bytes, right_bytes)
+    }
+
+    // Performs a comparison of two vector<u8>s or byte vectors
+    public fun compare_u8_vector(left: vector<u8>, right: vector<u8>): Result {
+        let left_length = vector::length(&left);
+        let right_length = vector::length(&right);
+
+        let idx = 0;
+
+        while (idx < left_length && idx < right_length) {
+            let left_byte = *vector::borrow(&left, idx);
+            let right_byte = *vector::borrow(&right, idx);
+
+            if (left_byte < right_byte) {
+                return Result { inner: SMALLER }
+            } else if (left_byte > right_byte) {
+                return Result { inner: GREATER }
+            };
+            idx = idx + 1;
+        };
+
+        if (left_length < right_length) {
+            Result { inner: SMALLER }
+        } else if (left_length > right_length) {
+            Result { inner: GREATER }
+        } else {
+            Result { inner: EQUAL }
+        }
+    }
+
+    #[test]
+    public fun test_strings() {
+        use std::string;
+
+        let value0 = string::utf8(b"alpha");
+        let value1 = string::utf8(b"beta");
+        let value2 = string::utf8(b"betaa");
+
+        assert!(is_equal(&compare(&value0, &value0)), 0);
+        assert!(is_equal(&compare(&value1, &value1)), 1);
+        assert!(is_equal(&compare(&value2, &value2)), 2);
+
+        assert!(is_greater_than(&compare(&value0, &value1)), 3);
+        assert!(is_smaller_than(&compare(&value1, &value0)), 4);
+
+        assert!(is_smaller_than(&compare(&value0, &value2)), 5);
+        assert!(is_greater_than(&compare(&value2, &value0)), 6);
+
+        assert!(is_smaller_than(&compare(&value1, &value2)), 7);
+        assert!(is_greater_than(&compare(&value2, &value1)), 8);
+    }
+
+    #[test]
+    #[expected_failure]
+    public fun test_integer() {
+        // 1(0x1) will be larger than 256(0x100) after BCS serialization.
+        let value0: u128 = 1;
+        let value1: u128 = 256;
+
+        assert!(is_equal(&compare(&value0, &value0)), 0);
+        assert!(is_equal(&compare(&value1, &value1)), 1);
+
+        assert!(is_smaller_than(&compare(&value0, &value1)), 2);
+        assert!(is_greater_than(&compare(&value1, &value0)), 3);
+    }
+
+    #[test]
+    public fun test_u128() {
+        let value0: u128 = 5;
+        let value1: u128 = 152;
+        let value2: u128 = 511; // 0x1ff
+
+        assert!(is_equal(&compare(&value0, &value0)), 0);
+        assert!(is_equal(&compare(&value1, &value1)), 1);
+        assert!(is_equal(&compare(&value2, &value2)), 2);
+
+        assert!(is_smaller_than(&compare(&value0, &value1)), 2);
+        assert!(is_greater_than(&compare(&value1, &value0)), 3);
+
+        assert!(is_smaller_than(&compare(&value0, &value2)), 3);
+        assert!(is_greater_than(&compare(&value2, &value0)), 4);
+
+        assert!(is_smaller_than(&compare(&value1, &value2)), 5);
+        assert!(is_greater_than(&compare(&value2, &value1)), 6);
+    }
+
+    #[test_only]
+    struct Complex has drop {
+        value0: vector<u128>,
+        value1: u8,
+        value2: u64,
+    }
+
+    #[test]
+    public fun test_complex() {
+        let value0_0 = vector::empty();
+        vector::push_back(&mut value0_0, 10);
+        vector::push_back(&mut value0_0, 9);
+        vector::push_back(&mut value0_0, 5);
+
+        let value0_1 = vector::empty();
+        vector::push_back(&mut value0_1, 10);
+        vector::push_back(&mut value0_1, 9);
+        vector::push_back(&mut value0_1, 5);
+        vector::push_back(&mut value0_1, 1);
+
+        let base = Complex {
+            value0: value0_0,
+            value1: 13,
+            value2: 41,
+        };
+
+        let other_0 = Complex {
+            value0: value0_1,
+            value1: 13,
+            value2: 41,
+        };
+
+        let other_1 = Complex {
+            value0: copy value0_0,
+            value1: 14,
+            value2: 41,
+        };
+
+        let other_2 = Complex {
+            value0: value0_0,
+            value1: 13,
+            value2: 42,
+        };
+
+        assert!(is_equal(&compare(&base, &base)), 0);
+        assert!(is_smaller_than(&compare(&base, &other_0)), 1);
+        assert!(is_greater_than(&compare(&other_0, &base)), 2);
+        assert!(is_smaller_than(&compare(&base, &other_1)), 3);
+        assert!(is_greater_than(&compare(&other_1, &base)), 4);
+        assert!(is_smaller_than(&compare(&base, &other_2)), 5);
+        assert!(is_greater_than(&compare(&other_2, &base)), 6);
+    }
+}

package/src/internal/move/jwks/build/jwk/sources/dependencies/AptosStdlib/copyable_any.move

@@ -0,0 +1,45 @@
+module aptos_std::copyable_any {
+    use aptos_std::type_info;
+    use aptos_std::from_bcs::from_bytes;
+    use std::bcs;
+    use std::error;
+    use std::string::String;
+
+    /// The type provided for `unpack` is not the same as was given for `pack`.
+    const ETYPE_MISMATCH: u64 = 0;
+
+    /// The same as `any::Any` but with the copy ability.
+    struct Any has drop, store, copy {
+        type_name: String,
+        data: vector<u8>
+    }
+
+    /// Pack a value into the `Any` representation. Because Any can be stored, dropped, and copied this is
+    /// also required from `T`.
+    public fun pack<T: drop + store + copy>(x: T): Any {
+        Any {
+            type_name: type_info::type_name<T>(),
+            data: bcs::to_bytes(&x)
+        }
+    }
+
+    /// Unpack a value from the `Any` representation. This aborts if the value has not the expected type `T`.
+    public fun unpack<T>(self: Any): T {
+        assert!(type_info::type_name<T>() == self.type_name, error::invalid_argument(ETYPE_MISMATCH));
+        from_bytes<T>(self.data)
+    }
+
+    /// Returns the type name of this Any
+    public fun type_name(self: &Any): &String {
+        &self.type_name
+    }
+
+    #[test_only]
+    struct S has store, drop, copy { x: u64 }
+
+    #[test]
+    fun test_any() {
+        assert!(unpack<u64>(pack(22)) == 22, 1);
+        assert!(unpack<S>(pack(S { x: 22 })) == S { x: 22 }, 2);
+    }
+}