feat(be): implement SMTP Gateway Protocol for email reception PoC

Add `smtp_request` and `smtp_request_validate` canister endpoints
following the SMTP Gateway Protocol spec. Emails to whitelisted
users (arshavir, thomas, shiling, igor, ruediger, bjoern) at
@beta.id.ai are accepted and stored in a new `smtp_postbox` stable
BTreeMap, keeping the 10 most recent emails per recipient.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: aterga

src/internet_identity/internet_identity.did

@@ -1034,6 +1034,44 @@ type ListAvailableAttributesError = variant {
     AuthorizationError : principal;
 };
 
+// SMTP Gateway Protocol types
+// ============================
+type SmtpHeader = record {
+    name : text;
+    value : text;
+};
+
+type SmtpMessage = record {
+    headers : vec SmtpHeader;
+    body : blob;
+};
+
+type SmtpAddress = record {
+    user : text;
+    domain : text;
+};
+
+type SmtpEnvelope = record {
+    from : SmtpAddress;
+    to : SmtpAddress;
+};
+
+type SmtpRequest = record {
+    message : opt SmtpMessage;
+    envelope : opt SmtpEnvelope;
+    gateway_flags : opt vec text;
+};
+
+type SmtpRequestError = record {
+    code : nat64;
+    message : text;
+};
+
+type SmtpResponse = variant {
+    Ok : record {};
+    Err : SmtpRequestError;
+};
+
 service : (opt InternetIdentityInit) -> {
     // Legacy identity management API
     // ==============================
@@ -1239,4 +1277,9 @@ service : (opt InternetIdentityInit) -> {
 
     // Looks up identity number when called with a recovery phrase
     lookup_caller_identity_by_recovery_phrase : () -> (opt IdentityNumber);
+
+    // SMTP Gateway Protocol
+    // =====================
+    smtp_request : (SmtpRequest) -> (SmtpResponse);
+    smtp_request_validate : (SmtpRequest) -> (SmtpResponse) query;
 };

src/internet_identity/src/main.rs

@@ -33,6 +33,7 @@ use internet_identity_interface::internet_identity::types::vc_mvp::{
     GetIdAliasError, GetIdAliasRequest, IdAliasCredentials, PrepareIdAliasError,
     PrepareIdAliasRequest, PreparedIdAlias,
 };
+use internet_identity_interface::internet_identity::types::smtp::{SmtpRequest, SmtpResponse};
 use internet_identity_interface::internet_identity::types::*;
 use serde_bytes::ByteBuf;
 use std::collections::HashMap;
@@ -53,6 +54,7 @@ mod http;
 mod ii_domain;
 
 mod openid;
+mod smtp;
 mod state;
 mod stats;
 mod storage;
@@ -1441,6 +1443,21 @@ mod attribute_sharing_old_vc {
     }
 }
 
+mod smtp_gateway {
+    use super::*;
+    use internet_identity_interface::internet_identity::types::smtp::{SmtpRequest, SmtpResponse};
+
+    #[update]
+    fn smtp_request(request: SmtpRequest) -> SmtpResponse {
+        smtp::handle_smtp_request(request)
+    }
+
+    #[query]
+    fn smtp_request_validate(request: SmtpRequest) -> SmtpResponse {
+        smtp::handle_smtp_request_validate(request)
+    }
+}
+
 fn main() {}
 
 // Order dependent: do not move above any exposed canister method!

src/internet_identity/src/smtp.rs

@@ -0,0 +1,41 @@
+use crate::state;
+use crate::storage::storable::smtp::StorableEmail;
+use internet_identity_interface::internet_identity::types::smtp::{
+    validate_envelope_only, SmtpRequest, SmtpResponse, ValidatedSmtpRequest,
+};
+
+pub fn handle_smtp_request(request: SmtpRequest) -> SmtpResponse {
+    let validated: ValidatedSmtpRequest = match request.try_into() {
+        Ok(v) => v,
+        Err(response) => return response,
+    };
+
+    let email = StorableEmail {
+        sender: validated.sender,
+        recipient: validated.recipient.clone(),
+        subject: validated.subject,
+        body: validated.body,
+    };
+
+    state::storage_borrow_mut(|storage| {
+        storage.store_email(validated.recipient, email);
+    });
+
+    SmtpResponse::Ok {}
+}
+
+pub fn handle_smtp_request_validate(request: SmtpRequest) -> SmtpResponse {
+    // If a full message is present, run full validation
+    if request.message.is_some() {
+        return match ValidatedSmtpRequest::try_from(request) {
+            Ok(_) => SmtpResponse::Ok {},
+            Err(response) => response,
+        };
+    }
+
+    // Otherwise validate just the envelope (and whatever else is present)
+    match validate_envelope_only(&request) {
+        Ok(()) => SmtpResponse::Ok {},
+        Err(response) => response,
+    }
+}

src/internet_identity/src/storage.rs

@@ -130,6 +130,7 @@ use storable::discrepancy_counter::{DiscrepancyType, StorableDiscrepancyCounter}
 use storable::fixed_anchor::StorableFixedAnchor;
 use storable::openid_credential::StorableOpenIdCredential;
 use storable::openid_credential_key::StorableOpenIdCredentialKey;
+use storable::smtp::{StorableEmail, StorableEmailAddress, StorableEmailList};
 use storable::storable_persistent_state::StorablePersistentState;
 
 pub mod anchor;
@@ -178,6 +179,7 @@ const LOOKUP_APPLICATION_WITH_ORIGIN_MEMORY_INDEX: u8 = 19u8;
 const STABLE_ANCHOR_APPLICATION_CONFIG_MEMORY_INDEX: u8 = 20u8;
 const LOOKUP_ANCHOR_WITH_RECOVERY_PHRASE_PRINCIPAL_MEMORY_INDEX: u8 = 21u8;
 const LOOKUP_ANCHOR_WITH_PASSKEY_PUBKEY_HASH_MEMORY_INDEX: u8 = 22u8;
+const SMTP_POSTBOX_MEMORY_INDEX: u8 = 23u8;
 
 const ANCHOR_MEMORY_ID: MemoryId = MemoryId::new(ANCHOR_MEMORY_INDEX);
 const ARCHIVE_BUFFER_MEMORY_ID: MemoryId = MemoryId::new(ARCHIVE_BUFFER_MEMORY_INDEX);
@@ -215,6 +217,8 @@ const LOOKUP_ANCHOR_WITH_RECOVERY_PHRASE_PRINCIPAL_MEMORY_ID: MemoryId =
 const LOOKUP_ANCHOR_WITH_PASSKEY_PUBKEY_HASH_MEMORY_ID: MemoryId =
     MemoryId::new(LOOKUP_ANCHOR_WITH_PASSKEY_PUBKEY_HASH_MEMORY_INDEX);
 
+const SMTP_POSTBOX_MEMORY_ID: MemoryId = MemoryId::new(SMTP_POSTBOX_MEMORY_INDEX);
+
 // The bucket size 128 is relatively low, to avoid wasting memory when using
 // multiple virtual memories for smaller amounts of data.
 // This value results in 256 GB of total managed memory, which should be enough
@@ -327,6 +331,9 @@ pub struct Storage<M: Memory> {
     lookup_anchor_with_passkey_pubkey_hash_memory_wrapper: MemoryWrapper<ManagedMemory<M>>,
     pub(crate) lookup_anchor_with_passkey_pubkey_hash_memory:
         StableBTreeMap<Principal, StorableAnchorNumber, ManagedMemory<M>>,
+
+    smtp_postbox_memory_wrapper: MemoryWrapper<ManagedMemory<M>>,
+    smtp_postbox: StableBTreeMap<StorableEmailAddress, StorableEmailList, ManagedMemory<M>>,
 }
 
 #[repr(C, packed)]
@@ -410,6 +417,7 @@ impl<M: Memory + Clone> Storage<M> {
             memory_manager.get(LOOKUP_ANCHOR_WITH_RECOVERY_PHRASE_PRINCIPAL_MEMORY_ID);
         let lookup_anchor_with_passkey_pubkey_hash_memory =
             memory_manager.get(LOOKUP_ANCHOR_WITH_PASSKEY_PUBKEY_HASH_MEMORY_ID);
+        let smtp_postbox_memory = memory_manager.get(SMTP_POSTBOX_MEMORY_ID);
 
         let registration_rates = RegistrationRates::new(
             MinHeap::init(registration_ref_rate_memory.clone())
@@ -510,6 +518,8 @@ impl<M: Memory + Clone> Storage<M> {
             lookup_anchor_with_passkey_pubkey_hash_memory: StableBTreeMap::init(
                 lookup_anchor_with_passkey_pubkey_hash_memory,
             ),
+            smtp_postbox_memory_wrapper: MemoryWrapper::new(smtp_postbox_memory.clone()),
+            smtp_postbox: StableBTreeMap::init(smtp_postbox_memory),
         }
     }
 
@@ -1829,6 +1839,28 @@ impl<M: Memory + Clone> Storage<M> {
         self.header.version
     }
 
+    pub fn store_email(&mut self, recipient: String, email: StorableEmail) {
+        use internet_identity_interface::internet_identity::types::smtp::MAX_EMAILS_PER_USER;
+
+        let key = StorableEmailAddress(recipient);
+        let mut list = self
+            .smtp_postbox
+            .get(&key)
+            .unwrap_or(StorableEmailList {
+                emails: Vec::new(),
+            });
+
+        list.emails.push(email);
+
+        // Keep only the most recent emails
+        if list.emails.len() > MAX_EMAILS_PER_USER {
+            let start = list.emails.len() - MAX_EMAILS_PER_USER;
+            list.emails = list.emails.split_off(start);
+        }
+
+        self.smtp_postbox.insert(key, list);
+    }
+
     pub fn memory_sizes(&self) -> HashMap<String, u64> {
         HashMap::from_iter(vec![
             ("header".to_string(), self.header_memory.size()),
@@ -1905,6 +1937,10 @@ impl<M: Memory + Clone> Storage<M> {
                 self.lookup_anchor_with_passkey_pubkey_hash_memory_wrapper
                     .size(),
             ),
+            (
+                "smtp_postbox".to_string(),
+                self.smtp_postbox_memory_wrapper.size(),
+            ),
         ])
     }
 }

src/internet_identity/src/storage/storable.rs

@@ -17,5 +17,6 @@ pub mod openid_credential;
 pub mod openid_credential_key;
 pub mod passkey_credential;
 pub mod recovery_key;
+pub mod smtp;
 pub mod special_device_migration;
 pub mod storable_persistent_state;

src/internet_identity/src/storage/storable/smtp.rs

@@ -0,0 +1,69 @@
+use candid::{CandidType, Deserialize};
+use ic_stable_structures::storable::Bound;
+use ic_stable_structures::Storable;
+use internet_identity_interface::internet_identity::types::smtp::{
+    MAX_BODY_BYTES, MAX_EMAILS_PER_USER, MAX_EMAIL_DOMAIN_BYTES, MAX_EMAIL_USER_BYTES,
+    MAX_SUBJECT_BYTES,
+};
+use std::borrow::Cow;
+
+/// Max serialized size of a single email address key.
+/// user (64) + "@" (1) + domain (255) + Candid overhead (~20 bytes).
+const STORABLE_EMAIL_ADDRESS_MAX_SIZE: u32 = (MAX_EMAIL_USER_BYTES + 1 + MAX_EMAIL_DOMAIN_BYTES + 20) as u32;
+
+/// Max serialized size of a single email.
+/// sender (320) + recipient (320) + subject (256) + body (5_000) + Candid overhead (~100 bytes).
+const STORABLE_EMAIL_MAX_SIZE: u32 =
+    (MAX_EMAIL_USER_BYTES + 1 + MAX_EMAIL_DOMAIN_BYTES) as u32 * 2
+    + MAX_SUBJECT_BYTES as u32
+    + MAX_BODY_BYTES as u32
+    + 100;
+
+/// Max serialized size of the email list value.
+const STORABLE_EMAIL_LIST_MAX_SIZE: u32 = STORABLE_EMAIL_MAX_SIZE * MAX_EMAILS_PER_USER as u32 + 100;
+
+#[derive(Clone, Debug, CandidType, Deserialize, Ord, PartialOrd, Eq, PartialEq)]
+pub struct StorableEmailAddress(pub String);
+
+impl Storable for StorableEmailAddress {
+    fn to_bytes(&self) -> Cow<'_, [u8]> {
+        Cow::Owned(candid::encode_one(self).expect("failed to encode StorableEmailAddress"))
+    }
+
+    fn from_bytes(bytes: Cow<'_, [u8]>) -> Self {
+        candid::decode_one(&bytes).expect("failed to decode StorableEmailAddress")
+    }
+
+    const BOUND: Bound = Bound::Bounded {
+        max_size: STORABLE_EMAIL_ADDRESS_MAX_SIZE,
+        is_fixed_size: false,
+    };
+}
+
+#[derive(Clone, Debug, CandidType, Deserialize)]
+pub struct StorableEmail {
+    pub sender: String,
+    pub recipient: String,
+    pub subject: String,
+    pub body: String,
+}
+
+#[derive(Clone, Debug, CandidType, Deserialize)]
+pub struct StorableEmailList {
+    pub emails: Vec<StorableEmail>,
+}
+
+impl Storable for StorableEmailList {
+    fn to_bytes(&self) -> Cow<'_, [u8]> {
+        Cow::Owned(candid::encode_one(self).expect("failed to encode StorableEmailList"))
+    }
+
+    fn from_bytes(bytes: Cow<'_, [u8]>) -> Self {
+        candid::decode_one(&bytes).expect("failed to decode StorableEmailList")
+    }
+
+    const BOUND: Bound = Bound::Bounded {
+        max_size: STORABLE_EMAIL_LIST_MAX_SIZE,
+        is_fixed_size: false,
+    };
+}

src/internet_identity_interface/src/internet_identity/types.rs

@@ -23,6 +23,7 @@ mod api_v2;
 pub mod attributes;
 pub mod icrc3;
 pub mod openid;
+pub mod smtp;
 pub mod vc_mvp;
 
 // re-export v2 types without the ::v2 prefix, so that this crate can be restructured once v1 is removed