feat: update access token environment variables and enhance device signing process for E2EE agents; add verification script and system flow documentation

shell/matrix/client.go

@@ -150,6 +150,41 @@ func (c *Client) FetchCrossSigningKeys(ctx context.Context, recoveryKey string)
 	return fetchCrossSigningKeysCore(ctx, &olmSSSSFetcher{machine}, recoveryKey)
 }
 
+// SignOwnDevice signs the bot's current device with the self-signing key.
+// This is the step that makes Element show the device as "verified".
+// Must be called after cross-signing private keys are available (via
+// FetchCrossSigningKeys or GenerateAndUploadCrossSigningKeys).
+// It force-fetches device keys from the server first to ensure the local
+// store has the correct signing key.
+func (c *Client) SignOwnDevice(ctx context.Context) error {
+	wrapper, ok := c.raw.Crypto.(*mautrixCryptoWrapper)
+	if !ok || wrapper == nil {
+		return fmt.Errorf("crypto not initialized")
+	}
+	machine := wrapper.Machine()
+	if machine == nil {
+		return fmt.Errorf("olm machine not available")
+	}
+
+	// Force-fetch own device keys so the local store has the correct signing key.
+	// Without this, SignOwnDevice fails with "different signing key" when the
+	// store has a stale or empty entry.
+	devices, err := machine.FetchKeys(ctx, []id.UserID{c.raw.UserID}, true)
+	if err != nil {
+		return fmt.Errorf("fetch own device keys: %w", err)
+	}
+	userDevices, ok := devices[c.raw.UserID]
+	if !ok {
+		return fmt.Errorf("own user not found in fetched keys")
+	}
+	device, ok := userDevices[c.raw.DeviceID]
+	if !ok {
+		return fmt.Errorf("own device %s not found in fetched keys", c.raw.DeviceID)
+	}
+
+	return machine.SignOwnDevice(ctx, device)
+}
+
 // fetchCrossSigningKeysCore contains the testable logic for SSSS key retrieval.
 func fetchCrossSigningKeysCore(ctx context.Context, fetcher ssssKeyFetcher, recoveryKey string) error {
 	keyID, keyData, err := fetcher.GetDefaultKeyData(ctx)