feat: adds accessors for caller attributes

Changelog.md

@@ -1,6 +1,8 @@
 ## Next
 * Add `Principal.toActor` — inverse of `fromActor`, casts a Principal to a typed actor reference (#490).
 
+* Adds new `CallerAttributes` module for the new caller attributes IC feature (#491).
+
 ## 2.4.0
 * Fix `Float32.rem` to use native `%` operator instead of round-tripping through `Float` (#482).
 * Flip x/y arg names in `arctan2` functions (#481).

mops.toml

@@ -21,8 +21,8 @@ base-0-14-13 = "https://github.com/dfinity/motoko-base#moc-0.14.13@794174a307975
 bench-helper = "0.0.3"
 
 [requirements]
-moc = "1.4.1"
+moc = "1.6.0"
 
 [toolchain]
-moc = "1.4.1"
+moc = "1.6.0"
 wasmtime = "35.0.0"

package.json

@@ -35,7 +35,7 @@
     "fast-glob": "^3.3.2",
     "ic-mops": "^2.7.0",
     "mo-dev": "^0.13.0",
-    "motoko": "^4.0.1",
+    "motoko": "^4.5.0",
     "npm-run-all": "^4.1.5",
     "prettier": "2",
     "prettier-plugin-motoko": "^0.11.2",

src/CallerAttributes.mo

@@ -0,0 +1,52 @@
+/// Allows accessing the Internet Computer's caller attributes.
+/// TODO: link to official documentation, once it's available.
+///
+/// ```motoko name=import
+/// import CallerAttributes "mo:core/CallerAttributes";
+/// ```
+
+import Prim "mo:⛔";
+import Text "Text";
+import Iter "Iter";
+import Runtime "Runtime";
+import Principal "Principal";
+
+module {
+  /// Returns the attribute data attached to the current call, but only
+  /// when the signer is listed in the `trusted_attribute_signers`
+  /// canister environment variable.
+  ///
+  /// Returns `null` if the current call carries no caller attributes.
+  /// Traps if the signer isn't trusted.
+  ///
+  /// `trusted_attribute_signers` is expected to be a comma-separated list
+  /// of principal texts, for example:
+  /// `"aaaaa-aa,un4fu-tqaaa-aaaab-qadjq-cai"`.
+  ///
+  /// Example:
+  /// ```motoko include=import no-validate
+  /// persistent actor {
+  ///   public shared func handle() : async () {
+  ///     switch (CallerAttributes.getAttributes()) {
+  ///       case (?data) { /* attributes came from a trusted signer */ };
+  ///       case null { /* no attributes, or signer is not trusted */ };
+  ///     };
+  ///   };
+  /// }
+  /// ```
+  public func getAttributes<system>() : ?Blob {
+    let signerBlob : Blob = Prim.callerInfoSigner<system>();
+    // An empty signer means no attributes where sent in this call.
+    if (signerBlob.size() == 0) {
+      return null
+    };
+    let signer = Principal.fromBlob(signerBlob);
+    let ?trustedSigners = Runtime.envVar<system>("trusted_attribute_signers") else {
+      Runtime.trap("trusted_attribute_signers environment variable is not set")
+    };
+    if (trustedSigners.split(#char(',')).any(func(t) { Principal.fromText(t) == signer })) {
+      return ?Prim.callerInfoData<system>()
+    };
+    Runtime.trap("untrusted attribute signer")
+  }
+}

validation/api/api.lock.json

@@ -88,6 +88,12 @@
       "public func toText(self : Bool) : Text"
     ]
   },
+  {
+    "name": "CallerAttributes",
+    "exports": [
+      "public func getAttributes<system>() : ?Blob"
+    ]
+  },
   {
     "name": "CertifiedData",
     "exports": [